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About This Book 



NetView Customization: Writing Command Lists describes how to write command 
lists tor the NetView™ program using either the Restructured Extended Executor 
language (rexx) or the NetView command list language. 

This book is intended to aid the customer in writing command lists. It primarily 
contains general-use programming interfaces, which allow the customer to write 
programs that use the services of the NetView program. However, this book also 
provides the following types of information, which are explicitly identified where 
they occur: Other product information, such as defining command lists within 
NetView and implementing message automation is provided to allow the customer 
to use the NetView program. This information should never be used as program- 
ming interface information. 



Who Should Use This Book 



NetView Customization: Writing Command Lists is designed for system program- 
mers and network operators who are either using command lists or learning how 
to write command lists. Before you read this book, you should be familiar with how 
the NetView program is used in your network and what the operators' tasks are. 
This book does not provide descriptions of NetView operator commands. If a 
command is unfamiliar, refer to NetView Operation. 



How to Use This Book 

This section includes information about the organization, the terms, and the coding 
conventions used in this book. 

How This Book Is Organized 

This book is organized into the following sections: 

"Part One. Basic Command List Topics" contains an overview of basic command 
list topics that are common to command lists written in either rexx or the NetView 
command list language. 

"Part Two. Writing Command Lists in the Restructured Extended Executor 
Language" contains information about how to write command lists using rexx. 

"Part Three. Writing Command Lists in the NetView Command List Language" 
contains information about how to write command lists using the NetView 
command list language. 

"Part Four. Advanced Command List Topics" contains information on advanced 
topics that pertain to command lists written in either rexx or the NetView command 
list language. 



tm NetView is a trademark of International Business Machines Corporation. 
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Appendix A, "REXX Command List Reference Summary" contains summary charts 
of the instructions and functions provided by the NetView program for use in rexx 
command lists. 

Appendix B, " NetView Command List Language Reference Summary" contains 
summary charts of all control keywords, control variables, and built-in functions for 
the NetView command list language. 

Appendix C, "Comparison of REXX and NetView Command List Language," con- 
tains a comparison between the features of rexx and the NetView command list 
language. 

Appendix D, "Converting Command Lists Written in the NetView Command List 
Language to REXX," contains information about converting command lists written 
in the NetView command list language to rexx. 

Notes on Terms Used in This Book 

Following is a list of terms and the meanings they have in this book. Unless other- 
wise noted, the abbreviations for products refer to the latest version and release of 
the product. 

Term Meaning 

command lists command lists written in rexx and command lists written in 

the NetView command list language 

member member in the specified data set (mvs) and file name with a 

file type of nccflst (vm) 

MVS mvs/xa, and mvs/esa (compatability mode) 

REXX Restructured Extended Executor language (see note 1) 

REXX Reference VM/SP System Product Interpreter Reference or TSO/E 

REXX Reference 

REXX User's Guide VM/SP System Product Interpreter User's Guide or TSO/E 
REXX User's Guide 

VM vm/sp, vm/sp hpo, and vm/xa (see note 2) 

VTAM VTAM V3R1.1, VTAM V3R1.2, and VTAM V3R2. 

Notes: 

1. NetView does not support rexx on vm/xa systems. 

2. vm/xa runs in compatability mode. 

Coding Conventions Used in This Book 

The model statements are formatted according to a set of coding conventions 
which are described in this section. 

Braces { } 

When braces enclose operands, this indicates that you must choose one 
of the operands. Any accompanying commas or equal signs must be 
included. Do not include braces when coding. 
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Brackets [ ] 

When brackets enclose an operand, this indicates a completely optional 
specification. Any accompanying commas or equal signs are optional. 
Do not include brackets when coding the specification. 

Ellipsis ... 

An ellipsis replaces a repetition of an operand or variable in syntax 
statements. Replace ellipses with the appropriate operand or variable 
when you code. 

OR-sign | 

The OR-sign separates choices for an optional or required specification. 
If a group of options is enclosed by brackets, and the individual options 
are separated by OR-signs, none of the options in the group has to be 
chosen. Do not include the OR-sign when coding the specification. 

UPPERCASE Characters 

You must enter command names or operands shown in UPPERCASE, 
BOLD characters exactly as they appear. These names are program 
keywords. 

lowercase Characters 

Lowercase, italic characters describe the kind of program variable 
information that must be supplied, rather than the literal information. 
The actual value replaces the lowercase description. 

underscored Characters 

Underscored characters indicate default values. These values are auto- 
matically assigned unless you specify a different value. 



What Is New In This Book 

In previous releases of NetView, this book was titled NetView Command Lists. 

Major changes made to this book include information about the Restructured 
Extended Executor (rexx) language. Release 3 of the NetView program has been 
enhanced to support rexx command lists. As a result, some existing chapters in 
this book have been changed to reflect new rexx information, and several new 
chapters have been added. 

Chapter 2, "Restructured Extended Executor Language Overview" on page 23 
contains an introduction to rexx and explains how to write rexx command lists for 
NetView. 

Chapter 3, "REXX Instructions Provided by NetView" on page 33 contains detailed 
information about using the new rexx instructions provided by NetView. 

Chapter 4, "REXX Functions Provided by NetView" on page 51 contains detailed 
information about using the new rexx functions provided by NetView. 

Appendix A, "REXX Command List Reference Summary" on page 171 contains a 
summary of the functions and instructions provided by the NetView program for 
use in rexx command lists for NetView. 

Appendix C, "Comparison of REXX and NetView Command List Language" on 
page 185 contains a comparison between the features of rexx and the NetView 
command list language. 
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Appendix D, "Converting Command Lists Written in the NetView Command List 
Language to REXX" on page 209 contains information about how to convert 
command lists written in the NetView command list language to rexx. 



Where To Find More Information 



Table 1 shows all of the publications in the NetView Release 3 library, arranged 
according to related tasks. For more information on these and other related publi- 
cations, see "Bibliography" on page 241. 

Table 1. The NetView Library 

Evaluation and Education 

Network Program Products General Information GC30-335O 

Bibliography and Master Index for NetView, NCP, and VTAM GC31-6081 

Learning about NetView: Operator Training (pc Diskettes) SK2T-0292 



Planning 

Network Program Products Planning 
NetView Storage Estimates (PC Diskettes) 
Console Automation Using NetView: Planning 



SC30-3351 
SK2T-1988 
SC31-6058 



Installation and Administration 

NetView Installation and Administration Guide 
NetView Administration Reference 
Network Program Products Samples 
NetView Tuning Guide 



SC31-6018 
SC31-6014 
SC30-3352 
SC31-6079 



Customization 

NetView Customization Guide 
NetView Customization: Writing Command Lists 
NetView Customization: Using PL/I and C 
NetView Customization: Using Assembler 



SC31-6016 
SC31-6015 
SC31-6037 
SC31-6078 



Operation 

NetView Operation Primer 

NetView Operation 

NetView Command Summary 



SC31-6020 
SC31-6019 
SX75-0026 



Diagnosis 

NetView Problem Determination and Diagnosis LY43-0001 

NetView Resource Alerts Reference SC31-6024 

NetView Problem Determination Supplement for LD21-0023 

Management Services Major Vectors 0001 and 0025 
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Chapter 1. Command List Overview 



This chapter is for those readers who need to understand what command lists for 
the NetView™ program are, how to use them, how to create them, and how to run 
them. 

This chapter is intended to provide customers with an overview of using command 
lists. It contains information on how to use, create, and run command lists. The 
information in this chapter must not be used for programming purposes. 



What Is a Command List 



A command list is a set of commands and special instructions that are grouped 
under one name like a computer program. For NetView, a command list can be 
written in either rexx or the NetView command list language. When you type a 
command list name at a terminal, the commands and instructions in that command 
list are interpreted and executed. There are several ways to run command lists 
besides entering a command list name at a terminal. For example, you can issue a 
timer command to run a command list at a specified time or time intervals. You 
can also run more than one command list at the same time under different tasks. 
See "How to Run Command Lists" on page 10 for more information on how to run 
command lists. 

Command lists help you control your network and make the operators' jobs easier. 
Command lists obtain information from operators, other tasks, system resources, 
or the contents of messages. The command list uses this information to perform 
processing or to decide the next action. This flexibility lets you automate repetitive 
or complex routine operations, perform resource recovery, and handle operations 
consistently among different operators. 



How Command Lists Can Help You 

Command lists help you automate your system and network in the following ways: 

• A command list can ask the operator questions and take action based on the 
answers. 

• A command list can display information on an operator's screen. 

• A command list can reword, delete, or reply to a message before the operator 
sees it. 

• A command list can wait for NetView to receive a message or group of mes- 
sages and take action based on the message content. 

• A command list can speed backup and recovery procedures (for example, 
automatic recovery of a failing resource). 

• A command list can tailor operator commands and procedures for your 
network. 
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• A command list can monitor and restart subsystems and programs (for 
example, vtam, cics, and DB2). 

System programmers or operators can write command lists to: 

• Simplify entry of operator commands 

• Ensure completeness and correct order when a sequence of commands must 
be issued 

• Provide for commands to be issued automatically when specific messages are 
received during the operation of systems, networks, and applications 

• Implement specialized operator dialogs that extend the operator's role or 
increase the efficiency and productivity of operators. 

Command lists can save time and make the operator's job easier in the following 
ways: 

• A command list can combine complex or multiple routine jobs or both. The 
operator can do all the jobs by entering the command list name at the terminal. 

• Complex or lengthy functions can be performed consistently among operators 
by using the same command list. 

Before you write a command list, it is important that you analyze your system and 
network operating procedures and the tasks that your operators regularly perform. 
Decide which of these jobs you want to automate using command lists. Start by 
writing simple command lists and add the more complex functions as you gain 
experience. This book does not describe how to use NetView operator commands. 
If you need information about an unfamiliar command, see NetView Operation. 

The following are examples of command lists that simplify network operation. 

Examples of Common Startup Command Lists 

If the operators need to set up terminal access facility (taf) sessions with the Infor- 
mation Management System (ims) and the Host Command Facility (hcf), a 
command list can be used instead of entering individual commands. 

The startupi command list in Figure 1 is an example of a rexx command list that 
can be used to establish terminal access facility (taf) sessions with ims and hcf. 



/* STARTUPl */ I 

•BGNSESS 0PCTL,APPLI0=IMS1,SRCLU=TAF11,L0GM0DE=0PCTLL06,SESSID=IMS , 1 

'BGNSESS 0PCTL,APPLID=HCF1,SRCLU=TAF11,L0GM0DE=0PCTLL0G,SESSID=HCFA , J 

•BGNSESS OPCTL,APPLID=HCFl,SRCLU=TAF12 f LOGMODE=OPCTLL0G,SESSID=HCFB' 1 

EXIT ■ j 

Figure 1. Common REXX Startup Command List 

The startup2 command list in Figure 2 on page 5 is an example of a command list 
written in the NetView command list language that can be used to establish the 
same terminal access facility sessions. 
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I STARTUP2 CLIST 

f BGNSESS 0PCTL,APPLID=IMS1,SRCLU=TAF11,L0GM0DE=0PCTLL0G,SESSID=IMS 
\ BGNSESS 0PCTL,APPLID=HCF1,SRCLU=TAF11,L0GM0DE=0PCTLL0G,SESSID=HCFA 
I BGNSESS 0PCTL,APPLID=HCF1,SRCLU=TAF12,L0GM0DE=0PCTLL0G,SESSID=HCFB 
I &EXIT 

Figure 2. Common NetView Command List Language Startup Command List 

Instead of having to remember and enter three commands, operators can now 
simply enter the command list name startupi or startup2. The command list starts 
the three sessions and operators receive the same messages that they would 
usually receive it they had entered all three commands. 

Examples of Activating a Network Control Program 

For operators who need to activate a Network Control Program (ncp), you can write 
a command list to simplify the activation of the ncp. Figure 3 is an example of a 
rexx command list that activates the ncp. 



/* HCP1 */ 

•V NET,ACT,ID=NCP1,L0AD=YES,L0ADSTA=LINK1 , 
\ EXIT 

Figure 3. REXX Command List to Activate a Network Control Program 

Figure 4 is an example of a command list written in the NetView command list lan- 
guage that activates that same ncp. 



I NCP2 CLIST 

I V NET,ACT,ID=NCP1,L0AD=YES,L0ADSTA=LINK1 

i &EXIT 

Figure 4. NetView Command List Language Command List to Activate a Network Control 
Program 

The operator can now use the ncpi or NCP2 command list to activate ncpl 

These are examples of simple command lists, illustrating some basic command list 
features. Both rexx and the NetView command list language provide the ability to 
perform additional functions. Detailed information about writing command lists in 
either language is provided in the following chapters. 



How Command Lists are Created 



You can create command lists before NetView is started or while it is running. 
Code each command list as a member of a command list data set. After you create 
the command list data set, you can use facilities such as ispf (for vm and mvs), 
iebupdte (for mvs), or xedit (for vm) to update the command list. 

NetView supports command lists in data sets that are concatenated across 
volumes. The member name is the command list name unless another name was 
defined for the command list on a cmdsyn statement. For more information on 
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For MVS 



ForVM 



cmdsyn, see NetView Administration Reference. The command list name can be 
from 1- to 8-characters (0-9, A-Z, @, $, #). The command list name must begin with 
a non-numeric character. 

Note: When NetView is operating on an mvs system and you plan to update or 
create command lists while NetView is running, define your command list data sets 
without secondary extents. Otherwise, a command list might be filed in a new 
extent, and you will have to stop and restart NetView to use the command list. 

Once a command list is created for mvs, the existence of the member is sufficient 
to allow an operator to run the command list. For vm, you must reaccess the mini- 
disk to use the command list. This is ail of the definition that is required to utilize 
the command list unless it is to be scope-protected or driven by a message. 



You must first create the data set that will be used to store the command lists. 
Code each command list as a separate member of a command list data set. To 
define the name of the command list data set to the NetView start procedure, code 
the jcl dd statement for the dsicld as shown in Figure 5. 



//DSICLD DD DSN=datasetnaine,DISP=SHR 
Figure 5. JCL to Define a Command List Data Set 

Data sets can be concatenated by coding the dsicld statement as shown in 
Figure 6. 



DSN =datasetnamel .DISP=SHR 
DSN= datasetname2 .DISP=SHR 
DSN= datasetname3 < DISP=SHR 
DSN= datasetnamen .DISP°SHR 

Figure 6. JCL to Define Concatenated Command List Data Sets 

The first command list data set defined under dsicld must have the largest block 
size of any concatenated command list data sets, or the first dd statement must 
have a dcb=(blksize=xxxx) statement where xxxx is equal to the largest block size 
of the concatenated data sets. 

Note: To make sure your command lists are accessed when they have the same 
name as IBM-supplied command list data sets, concatenate your command list 
data sets before the IBM-supplied ones. Make sure the block size is 3920 or less to 
reduce paging caused by the block size exceeding the size of a page of memory. 



You must create a file using the name of the command list as the file name with a 
file type of nccflst. Be sure to access the minidisk after you define the command 
list. 

Note: If there is not a cmdmdl statement associated with a command list written in 
the NetView command list language, the clist statement must be the first record of 
the command list. See "General Coding Conventions" on page 72 for information 
on coding a clist statement. 



//DSICLD 


DD 


// 


DD 


// 


DD 


// 


DD 
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Who Can Use Command Lists 



Once a command list is created, the NetView operator can use that command list 
by entering the command list name. 

You can limit command list access to a specific group of operators by causing 
NetView to scope check each command list when it is run. For each command list 
you want scope checked, include the cmdmdl statement shown in Figure 7 in the 
dsicmd member. 



I cmdlistname CMDMDL MOD = DSICCP 

Figure 7. CMDMDL Statement Syntax for Command Lists 

Following the cmdmdl statement, enter the appropriate cmdclass statement to 
reflect the restrictions that apply to your NetView system. For more information on 
how to code cmdmdl and cmdclass statements, see NetView Administration Refer- 
ence. 

Note: You must restart NetView after the new definitions are included in dsicmd to 
put the appropriate scope checking into effect. 

With NetView commands, you can scope check certain keywords that are entered 
with the commands using the keyclass definition statement. However, you cannot 
use keyclass to scope check parameters that are entered with a command list. 

If you need to scope check the parameters that are entered with a command list, 
you can execute a command list from a pl/i or c program. The program can then 
execute the command list and pass the parameters to the command list. For more 
information on writing programs in pl/i or c, see NetView Customization: Using PL/I 
andC. 



Loading Command Lists Into Storage 



NetView provides the ability to load command lists into main storage prior to exe- 
cution. 

Although it is not mandatory that you load a command list into main storage before 
it is executed, pre-loading promotes improved performance of your computer 
system. If you invoke a command list that has not been pre-loaded, it is loaded 
into main storage, executed, and then dropped from main storage. Therefore, 
every time the command list is executed, it must be retrieved from the auxiliary 
storage device where it resides. By pre-loading the command list, it can be exe- 
cuted multiple times without having to be retrieved from auxiliary storage each 
time. 

There are three NetView commands that allow you to move command lists into and 
out of main storage, and list command lists that are currently in main storage: 

LOADCL loads command lists into main storage shared by all operators. 

DROPCL drops a command list that was previously loaded into main storage 
using the loadcl command. 

MAPCL lists command lists that currently reside in main storage. 
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A description of each command is provided on the following pages. For additional 
information on the loadcl, dropcl, or mapcl command, refer to NetView Operation. 

The NetView program provides a sample rexx command list (CNMS8003) that can 
help you manage the number of command lists that have been loaded into storage 
using the loadcl command. The sample uses the mapcl and dropcl commands to 
conditionally drop commands from main storage. Browse the sample command 
list for more information on how it works. 



LOADCL Command 



Use the loadcl command to load command lists into main storage. Figure 8 
shows the syntax of the loadcl command. The operands can be entered in any 
order. 



LOADCL cmdlistnamet,...] [(REPLACE)] J 

Figure 8. LOADCL Command Syntax 

cmo7/'s/name[,...] 

for mvs, the names of the members within the dsicld mvs data set that contain 
the command lists to be loaded into storage. 

for vm, the names of the vm files that contain the command lists to be loaded 
into storage. The file type must be nccflst. 

Note: Any synonyms defined for a command list through the NetView cmdsyn 
command can be used with the loadcl command. 

(REPLACE) * 

indicates that you want to load new copies of any of the command lists that 
were previously loaded using loadcl. When all of the current users have fin- 
ished using the previously loaded copy, it is automatically dropped. 

If a command list is already loaded and replace is not specified, no load can 
occur for that command list. 

Note: If you change a command list that has already been loaded into main 
storage, you must issue the loadcl command with the (replace) operand specified. 
This loads the updated version of the command list into main storage so that it is 
executed instead of the old version. 

If you have command lists that are frequently executed, you can load them into 
main storage when NetView is initialized. For example, if the command lists 
startjob and setterm are run often, you can load them into main storage by coding 
the statements shown in Figure 9 in your initialization command list. After initial- 
ization, the startjob and setterm command lists will reside in main storage and 
are available for execution. 



LOADCL STARTJOB 
LOADCL SETTERM 

Figure 9. Examples of LOADCL Commanos 

For more information on loading command lists into storage when NetView is ini- 
tialized, refer to "NetView Initialization" on page 10. 
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DROPCL Command 

You can remove a command list from main storage by using the dropcl command. 
Figure 10 shows the syntax of the dropcl command. 



MAPCL Command 



wgxv^sMmMmm 



|OROPCL *|cmd7/staa/7?e[,...] 

iw,,..,,',,,. ■ ■.-..,.■ -i.. .:■,: .;. ■,..:.:...- \ ■::■-■■ y,. 
Figure 10. DROPCL Command Syntax 



indicates that all storage-resident command lists should be removed from 
main storage. 

cmdlistnamel,...'] 

for mvs, the names of the members within the dsicld mvs data set that contain 
the command lists to be removed from storage. 

for vm, the names of the vm files that contain the command lists to be removed 
from storage. The file type must be nccflst. 

Note: Any synonyms defined for a command list through the NetView cmdsyn 
command can be used with the dropcl command. 



The mapcl command can be used to list all command lists currently residing in 
main storage or to determine if a specific command list resides in main storage. 
For information on output displayed for mapcl, see NetView Operation. Figure 11 
shows the syntax of the mapcl command. 



| MAPCL [Z\cmdlistnamel,...J] 

'f .. . .,'..... ,.....'■-. 

Figure 11. MAPCL Command Syntax 



indicates that all storage-resident command lists should be listed. This is the 
default if mapcl is entered with no parameters. 

cmdlistname[,...'] 

for mvs, the names of the members within the dsicld mvs data set that contain 
the command lists that can reside in main storage. 

for vm, the names of the vm files that contain the command lists that can reside 
in main storage. The file type must be nccflst. 

If the command lists are storage-resident, they are listed. 

Note: Any synonyms defined for a command list through the NetView cmdsyn 
command. are not supported by this command. 
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How to Run Command Lists 

You should design command lists that run with little outside help from operators. 
Some of the ways command lists can be run are: 

• By NetView initialization 

• By operator logon to NetView 

• By message automation 

• By an operator command (including timer commands) 

• By another command list 

• By a user-written command processor. 

NetView Initialization 

You can define a command list to run automatically when NetView is started. The 
NetView initialization command list runs under the ppt task. See "Primary POI 
Task Restrictions" on page 17 for information about ppt restrictions. 

You can run only one command list at initialization, but this command list can call 
other command lists. "Another Command List" on page 13 explains the rules that 
apply to calling another command list. 

Code the name of the command list you want to run on the nccfic definition state- 
ment in dsidmn. For example, if you want to run the setup command list, code the 
nccfic statement as shown in Figure 12. 



NCCFIC IC=SETUP 

Figure 12. Example of NCCFIC Definition Statement 

The default nccfic statement coded in the sample dsidmn shipped with NetView is: 
NCCFIC IC=CNME1G34 DSIMSGG1 

This invokes command list cnmeio34 (the default initialization command list) with 
the parameter dsimsgoi. The parameter dsimsgoi is the name of the message auto- 
mation table that will be in effect when NetView is initialized. If you want to use 
another table, change this parameter. 

For more information on nccfic, see NetView Administration Reference. 

You can include many types of commands in your initialization command list. The 
following list describes some of the commands you may want to include: 



• 



To route unsolicited messages, include assign commands, assign commands 
allow you to automatically set up unsolicited message routing for the opera- 
tors. 

To start message automation, include automsg commands. 

NetView already includes the dsimsgoi member to set up message automation, 
and for running pdfilter when the hardware monitor is initialized. The 
automsg command is coded as follows: 

AUTOMSG MEMBER=DSIMS601 
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To establish authorized operators for the IBM-supplied message automation 
command lists, include the following statements: 

&CGL0BAL CGAUTHID1 
&CGAUTHIDl=operid 

To restore at, every, and after commands that were entered with the save 
option, include a restore timer command. By putting the restore timer 
command in your initialization command list, you ensure that the saved timer 
commands are restored at NetView initialization. By restricting use of the 
restore timer command to only the initialization command list, you ensure that 
the timers are restored only once. 

To start operator tasks that handle your system and network automation, 
include autotask commands. 

To load command lists into main storage, include loadcl commands. 



You can define a command list to run automatically after the operator successfully 
logs on. Only one command list can be defined to run when an operator logs on, 
but this command list can activate other command lists. Refer to "Another 
Command List" on page 13 for rules that apply when calling another command list. 
The name of the activating command list is coded in the operator's profile. 

Code the name of the command list you want to run in the operator's profile using 
the ic operand of the profile statement. For example, if you want to run the hello 
command list every time an operator logs on; and if the operator has a profile of 
profbeg, the ic operand (as shown in Figure 13) should be added to this profile. 



PROFBEG PROFILE IC=HELL0 

Figure 13. Example of PROFILE Definition Statement 

Note: Some operator ids are assigned by using the autotask command, which 
runs network automation tasks. Operator tasks started by the autotask command 
do not have a terminal attached (as specified in the profile statement for its oper- 
ator). Therefore, if an initial command list is to be run after the operator success- 
fully logs on (as specified on the ic operand of the operator's profile statement), 
the initial command list should not set any pf keys or invoke any NetView full- 
screen displays. 

For more information on the profile definition statement, see NetView Adminis- 
tration Reference. 

Message Automation 

A command list can be initiated by NetView upon receipt of a message. These 
command lists can send a command as an automatic response to the message, or 
they can use the genalert command to represent the event as an alert in the hard- 
ware monitor data base. For the format of the genalert command, see NetView 
Operation. 

Command lists initiated by NetView upon receipt of a message contain a series of 
commands to perform a function as a result of the message. For example, if the 
message reported that an ncp failed, the command list can issue the vtam 

Chapter 1. Command List Overview 11 



Basic Topics 



command to reactivate the ncp. See Chapter 9, "Message Automation" on 
page 135. 

Operator Command 

The operator can enter a command list name from the terminal in the same way 
any other command and operands are entered. When the name of the command 
list is entered, the command list starts processing. Message responses and other 
information can be sent to the operator, depending on how the command list is 
written. 

NetView operators can activate, stop, suspend, or restart command list processing 
by entering the NetView commands go, reset, stack, or unstack. For command 
lists written in rexx, the commands are entered when the command list is waiting 
for a response to a parse ext, parse pull, or wait instruction. For command lists 
written in the NetView command list language, the commands are entered during 
command list pauses or command list waits. The go command must precede any 
data entered in response to a parse ext or parse pull or in response to an &pause. 
For more information about the go, reset, stack, and unstack commands, see 
NetView Operation. 

Operators can use the following NetView commands to run command lists at a 
specified time or time interval: 

after instructs NetView to run the command list after a specified period of time. 

at instructs NetView to run the command list at a particular time. 

delay instructs NetView to wait the specified amount of time and then run the 
command list once. 

every instructs NetView to run the command list repeatedly at a certain time 
interval. 

You can set up the at, delay, every, and after commands so the command list runs 
even if the operator is not logged on at the time. This is done with the ppt operand. 
However, some commands cannot be used in a command list running under the 
ppt. Read "Primary POI Task Restrictions" on page 17 for more information. 

Operators can use the cmd command to queue a command list at a different priority 
than its default. 

Command lists can be defined so that they always interrupt the processing of other 
command lists. This is done using theTYPE= parameter of the cmdmdl statement in 
the dsicmd. For more information, see NetView Administration Reference. 

To learn more about the at, delay, every, after, and cmd commands, see NetView 
Operation. 
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Another Command List 

One command list can activate another command list. When a command list is 
running under the control of another command list, it is nested within the calling 
command list. To nest a command list within another command list, code the 
name of the called command list as a command within the controlling command 
list. When NetView reaches a statement with the name of a command list, NetView 
starts running the nested command list. When NetView reaches the end of the 
nested command list, NetView returns control to the calling command list and proc- 
esses the next statement. 

Command lists written in rexx and command lists written in the NetView command 
list language can call each other. A rexx command list can be invoked as a rexx 
command, subroutine, or function. A rexx command list can call a command list 
written in the NetView command list language as a command but not as a subrou- 
tine or a function. A command list written in the NetView command list language 
can call another command list written in the NetView command list language or a 
rexx command list as a command. For information about rexx subroutines and 
functions, see REXX User's Guide and REXX Reference. 

When rexx command lists and command lists written in the NetView command list 
language call each other, parameters can be passed from the calling command list 
to the nested command list. However, when the nested command list is finished, 
only a return code is returned to the calling command list. To pass variables 
between the calling command list and the nested command list, use NetView 
global variables. "REXX GLOBALV Instruction" on page 44 provides information 
about setting and retrieving global variables in rexx command lists. For informa- 
tion on defining global variables in command lists written in the NetView command 
list language, see Chapter 8, "NetView Command List Language Global Variables" 
on page 123. 

You can have 250 levels of externally nested command lists. This means that you 
can write a command list which activates another command list. The nested 
command list can activate a third command list. The third command list can then 
activate a fourth, and so on. To visualize how this process works, see Figure 14 
on page 14. 

Note: Only rexx command lists invoked as commands, external subroutines, or 
external functions count as one of the 250 levels of externally nested command 
lists. You can invoke up to 250 rexx command lists as internal subroutines and 
functions but they do not count toward the 250 levels of externally nested command 
lists. 

You should test each command list by itself before running the command list as 
part of a nested chain of command lists. If a nested command list encounters an 
unrecoverable error, the command list ends and passes the error back to the 
command list from which it was called. If the calling command list is written in 
rexx, it might be able to take action to recover from the error passed to it from the 
nested command list. For information on coding rexx command lists that can 
recover from errors, see "Recovering from Errors in REXX Command Lists" on 
page 31. If the calling command list is written in the NetView command list lan- 
guage, and an error occurs in the nested command list, the calling command list 
also ends. If the calling command list was called by another command list, it con- 
tinues to pass the error back to the command list from which it was called. 
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CMDLISTA 



CMDLISTB 



(last statement) 



CMDLISTB 



t 
CMDLISTC 



(last statement) 



CMDLISTC 



(last statement) 



Figure 14. Nested Command Lists 



User-Written Command Processor 

You can write a command processor that activates a command list. Command 
processors are programs written in languages such as Assembler, pl/i, or c. For 
information on how to write command processors, see NetView Customization: 
Using Assembler. 



Using Network Commands in Command Lists 

You can use network commands in a command list. The following is a partial list of 
some of the types of network commands you can include: 

• NetView commands 

• User-written NetView commands 

• vtam commands. 

The commands used within command lists are still limited by the operator's span 
of control and the scope of the commands. 

Notes: 

1. You cannot use the NetView return command. 

2. You can only use NetView and user-written commands that are defined on the 
cmdmdl statement as regular or both (type = r or type = b). 

3. You must use the appropriate prefix with session monitor (nldm), hardware 
monitor (npda), and status monitor (statmon) commands. 

The following sections describe how you can use NetView commands in command 
lists. 



Using System Commands 



System commands can be used in command lists. The NetView command mvs is 
available to enter mvs commands in command lists. For example, 'mvss jobname' 
or ' mvs d a,l ' . See NetView Operation for more information about the mvs 
command. 
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Using Long Running Commands 

You can use long running commands in your command lists. There are two types 
of long running commands: minor and major. The type of long running command, 
minor or major, and whether the command list uses the cmd command to queue 
the command, determines whether the long running command or the issuing 
command list receives execution priority. 

Using Minor Long Running Commands 

The NetView bgnsess (Flscn) and nccf commands are minor long running com- 
mands. When issued from a command list, a minor long running command per- 
forms syntax checking and other synchronous error tests. The value of the return 
code (rc in rexx command lists or &retcode in command lists written in the 
NetView command list language) contains the result of these tests. When the 
issuing command list is complete, the minor long running command is executed. 
Any errors that occur while the long running command is executing are reported in 
messages. To access these messages, use message automation, the trap and 
wait instructions (rexx), or the &wait control statement (NetView command list lan- 
guage). 

Notes: 

1. When a task receives a message, a check is first made to determine if a 
command list is waiting for a message. If not and if message automation is 
being used, then the message is checked against the message automation 
table. Once a message is used by a command list for wait processing (trap 
and wait or &wait), that same message cannot be used by a message auto- 
mation table. 

2. You do not need to issue the nccf minor long running command from a 
command list because NetView ensures that the command facility screen is 
displayed whenever line mode messages are presented. 

To define a user-written command as a minor long running command, use the 
dsipush macro. See NetView Customization: Using Assembler for information on 
dsipush. 

Using Major Long Running Commands 

With the exception of the bgnsess (flscn) and nccf commands, all other long 
running commands are major long running commands. When a major long running 
command is issued from a command list, execution of the command list is sus- 
pended while the command executes. It may be necessary for the operator to indi- 
cate that the major long running command is complete by issuing a return or end 
command before the calling command list resumes processing. 

If a command list issues a major long running command, and while the command 
is executing, the same major long running command is entered, the first command 
is canceled. The major long running command then passes control to the issuing 
command list: 

• When the issuing command list is written in rexx, it is recommended that you 
code signal on halt. If you do not code signal on halt, the operator will see 
inappropriate termination messages. You should code exit -5, and you should 
not generate any messages in the halt subroutine. See "Recovering from 
Errors in REXX Command Lists" on page 31 for more information on coding 

SIGNAL ON HALT. 
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• When the issuing command list is written in the NetView command list lan- 
guage, the command list is also canceled. 

You can also cancel the calling command list with the unique command. See 
NetView Operation for information on unique. 

Queuing Long Running Commands 

You can control the execution of long running commands by using the NetView cmd 
command to queue them. When queued, all long running commands are proc- 
essed in the same manner, regardless of whether the command is minor or major. 
Queuing a long running command causes it to be processed independently of your 
command list. The result of the long running command does not influence the 
result of the command list. When you queue a long running command, the return 
code indicates the result of the queuing operation only. You cannot get a return 
code from the queued command. 

To ensure that taf command output is displayed before the command list resumes 
processing, use cmd high bgnsess flscn. If the operator rolls from the current long 
running command, the command list continues. If the long running command is 
canceled, the cancel is not passed back to the issuing command list. For more 
information on taf, see NetView Operation. 

To delay the execution of nldm until your command list is finished executing, is 
stacked, is canceled, or is otherwise interrupted, use cmd low nldm. 

Using the VIEW Command 

The view command can be used in command lists to display panels. The view 
command has access to local and global variables set in the command list that 
issues the view command. See NetView Customization Guide for more information 
on the view command. 

Using Full-Screen Commands 

If a command list that is executed from a full-screen processor issues a full-screen 
command, the NetView program can display the command facility screen before 
displaying the output of the full-screen command. The command facility screen is 
only displayed if the command list generates any other output that is displayed to 
the operator. Display of the command facility screen suspends any autowrap 
setting and prevents the full-screen output from being automatically displayed. To 
minimize the possibility of displaying command facility screen output, define and 
code the command list so that it does not generate any other output to be dis- 
played. For example: 

• Code a cmdmdl definition statement with echo=no for the command list. See 
NetView Administration Reference tor information on coding a cmdmdl state- 
ment. 

• Code trace errors or trace off at the beginning of a rexx command list or 
&control err at the beginning of a command list written in the NetView 
command list language. See REXX Reference or REXX User's Guide for infor- 
mation on the trace instruction. 

• Do not code any say instructions in a rexx command list or any &write or 
&begwrite control statements in a command list written in the NetView 
command list language. 

• Do not issue any commands that have line mode output. 
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Primary POI Task Restrictions 

Command lists run under the primary poi task (ppt) when they meet any of the fol- 
lowing criteria: 

• Routed to the ppt for execution as a result of message automation 

• Coded on an nccfic definition statement to run when NetView is initialized 

• Called with an at, every, after, or excmd command that uses the ppt as an 
operand, (ppt on at, every, and after allows the command to be run even 
when the operator who scheduled it is not logged on.) 

The following restrictions apply to command lists run under the ppt: 

• in general, full-screen commands and immediate commands cannot be used. 
Do not use the following NetView commands: 

- AUTOWRAP 

- BGNSESS 

- CLOSE 

- GO 

- INPUT 

- LOGOFF 

- MOVE 

- ROUTE 

- SET 

- START 

- STOP 

- SWITCH 

- WTO 

- WTOR. 

• Do not use the following rexx instructions: 

- FLUSHQ 

- MSGREAD 

- PARSE EXT 

- PARSE PULL 

- TRAP 

- WAIT. 

• Do not use the following NetView command list language control statements: 

- &PAUSE 

- &WAIT. 

• Do not execute command processors that use the mvs/gcs stimer macro. 

Note: Command lists running under the ppt should not generate messages con- 
taining non-Latin characters (double-byte character sets, such as Kanji) that will be 
routed to the system console. 
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AUTOTASK OST Restrictions 

Some command lists run under an ost which is started by an autotask command 
that sets up a subtask called an automation task. Command lists running under an 
automation task can handle message automation. 

Because an automation task handles message automation, it does not have a ter- 
minal logged on to it. Therefore, neither full-screen commands nor commands that 
support specific keyboard functions (such as set pf keys) are useful in automation 
task command lists. 



Writing Bilingual Command Lists 



A command list can be written in rexx, the NetView Command List language, or 
both. A command list written in both languages is referred to as a bilingual 
command list. 

Bilingual command lists help to ensure that consistent results are achieved when a 
common command list is executed by operators at multiple installations. For 
instance, you may have one installation that has the rexx interpreter installed and 
another that does not. If you create a bilingual command list that can be executed 
in both installations, you help to ensure that the results are consistent. All 
command lists reside on the same fixed record length library. 

NetView determines the language in which a command list is written by checking 
the first record of the command list. A rexx command list starts with a comment, 
so its first record must contain "/*" as the first two non-blank characters. The 
comment must end with the "7" characters. A command list written in the NetView 
command list language must have the character string clist in the first 71 charac- 
ters of its first record. The structure of the first record of a bilingual command list 
is as follows: 

1. Columns 1 and 2 must contain the characters "/* ". 

2. Beginning in column 3, there can be optional non-blank characters. 

3. Following any non-blank characters, there must be one or more blank charac- 
ters. 

4. The character string clist must follow the one or more blank characters. 

5. If any parameter variables are being passed, there must be one or more blank 
characters between the clist character string and the parameter variables. 

Note: You must code &exit at the end of the NetView command list language 
portion of a bilingual command list. You must code the characters "*/" before the 
beginning of the rexx portion. 
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When processing a bilingual command list, NetView determines whether to 
execute the rexx portion or the NetView command list language portion based on 
the following criteria: 



REXX 
Active? 



Command List 
First Record 



Action 



Yes 



I*. 



The rexx interpreter is invoked. The rexx portion of the 
command list is processed. The NetView command list 
language portion of the command list is treated as a 
comment. 



Yes /\..CLIST The rexx interpreter is invoked. The rexx portion of the 

command list is processed. The NetView command list 
language portion of the command list is treated as a 
comment. 



No 



NetView issues an error message. 



No /\..CLIST The NetView command list language interpreter is 

invoked. The NetView command list language portion 
of the command list is executed. The rexx portion of the 
command list is ignored. 

Yes|No Does not start The NetView command list language interpreter is 

with /*... invoked. 



Figure 15 provides an example of how bilingual command lists should be struc- 
tured. Because the first line of the command list contains "/*" in columns 1 and 2 
and ends with the character string clist, NetView recognizes the command list as 
bilingual. 



I /*SAMPLE CLIST 

I * AFTER THE FIRST RECORD WOULD BE 
I * THE COMMAND LIST WRITTEN IN THE 
* * NETVIEW COMMAND LIST LANGUAGE 



. (NETVIEW COMMAND LIST LANGUAGE PORTION OF THE COMMAND LIST) 

> THE NETVIEW COMMAND LIST LANGUAGE PORTION OF THE COMMAND LIST 
* WOULD END WITH &EXIT 
S£XIT 

V ■' 

J* OPTIONALLY, YOU MAY HAVE A COMMENT HERE THAT 

IDENTIFIES THE BEGINNING OF THE REXX PORTION OF 

THE COMMAND LIST */ 

. (REXX PORTION OF THE COMMAND LIST) 



Figure 15. Example of a Bilingual Command List 

For information on converting command lists written in the NetView command list 
language into rexx or bilingual command lists, see Appendix D, "Converting 
Command Lists Written in the NetView Command List Language to REXX" on 
page 209. 
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What an Operator Sees when a Command List Runs 

You can control the amount of data displayed to the operator during the execution 
of a command list. Responses to commands in the command list or messages the 
command list sends to the terminal screen can be displayed to the operator. 

To control the amount of data displayed to the operator during the execution of a 
rexx command list, use the trace instruction (see REXX Reference), the trap 
instruction, (see "REXX TRAP Instruction" on page 34), or the suppression char- 
acter (see "Suppressing Display of Non-REXX Commands" on page 25). 

To control the amount of data displayed to the operator during the execution of a 
command list written in the NetView command list language, use the &control 
control statement (see "&CONTROL Control Statement" on page 92), the &wait sup- 
press control statement (see "Customizing the &WAIT Statement" on page 118), or 
the suppression character (see "Conventions for Suppression Characters" on 
page 74). 

The commands and messages displayed during execution of a command list 
appear in the message area of the NetView screen. Output from the command list 
is preceded by a type code of c. For a complete description of the NetView screen 
layout and the format of messages sent to the screen, see NetView Operation. 
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Chapter 2. Restructured Extended Executor Language 
Overview 

This chapter offers a brief introduction to rexx. Not all of the features and syntax 
rules of rexx are described in this manual. This manual focuses primarily on the 
rexx instructions and functions provided by the NetView program. For more 
detailed information about rexx, see your REXX Reference or REXX User's Guide. 

Notes: 

1. In this book, REXX Reference refers to TSO/E REXX Reference for mvs users 
or VM/SP System Product Interpreter Reference for vm/sp users. 

2. In this book, REXX User's Guide refers to TSO/E REXX User's Guide for mvs 
users or VM/SP System Product Interpreter User's Guide for vm/sp users. 

3. NetView does not support rexx on vm/xa systems. 

4. For NetView to support rexx on mvs systems, tso/e must be installed but does 
not have to be active. 



Introduction to the Restructured Extended Executor Language 

rexx is an interpretive language. This means that the rexx interpreter operates 
directly on the program as it executes, line-by-line and word-by-word. An inter- 
preted language is different from other programming languages, such as cobol, 
because it does not have to be compiled before it is executed. 

Each rexx command list must begin with a comment. A comment is marked with 
"/*" at the beginning and "*/" at the end. You can insert comments in your rexx 
command list wherever necessary. 

A rexx command list consists of a series of clauses, each having a separate 
purpose. In a simple rexx command list, the clauses are interpreted in the 
sequence in which they are coded. You can control the sequence in which clauses 
are executed by using specific commands that alter the processing order. 

A rexx instruction tells the rexx interpreter to do something. A rexx instruction is 
identified by its keyword, which must be the first item in the clause. 

When an equal sign (=) is the second item in a clause, the clause is identified as 
an assignment clause. Assignment clauses allow you to give a value to a variable. 
Variables allow you to define different values for the clauses within a command 
list. 

When the second item in a clause is a colon (:), the clause is interpreted as a label. 
Labels serve to identify the target statement for a transfer of control. 

The rexx language allows you to call internal or external routines, called functions. 
rexx function names must always be followed by parentheses. There can be up to 
ten expressions, separated by commas, between the parentheses. An expression 
is something that can be computed. The rexx interpreter performs the computation 
named by the function and returns a result. The result is then used in the 
expression in place of the function call. To use a function, place the function name 
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in the command list at the location where you want the result to be accessed. 
There are also several built-in functions included in the rexx language that perform 
pre-defined operations. 

See REXX Reference or REXX User's Guide for a complete description of the fea- 
tures of the rexx language. 



Coding Conventions for REXX Command Lists 



Record Size 



This section describes the syntax rules that apply when coding rexx command lists 
for NetView. 



The records in rexx command lists for NetView can be up to 80 characters in 
length. If the first record of a rexx command list contains a sequence number in 
columns 73 through 80, then all records in that command list will be truncated to 72 
characters. 



Using Quotes 



To avoid variable substitution on a string in a rexx command list, enclose the string 
in either single quotes (') or double quotes ("). The quotes signify that you do not 
want rexx to perform variable substitution on the string. That is, you do not want 
the rexx interpreter to interpret the string. When rexx encounters a quote (single 
or double) on a command list statement, it stops interpreting until it reaches a 
matching quote. 



Do not enclose rexx instructions in quotes, rexx recognizes its own instructions 
and does not perform variable substitution on them. Following are some examples 
showing how quotes are used to prevent variable substitution with the rexx say 
instruction: 

SAY 'THIS IS A STRING WITH SINGLE QUOTES' 
SAY "THIS IS A STRING WITH DOUBLE QUOTES" 

These two instructions would display the following at your terminal: 

THIS IS A STRING WITH SINGLE QUOTES 
THIS IS A STRING WITH DOUBLE QUOTES 

To use an apostrophe or double quotes within the text of a string enclosed in 
quotes, you can do the following: 

SAY "IT'S EIGHT O'CLOCK. TIME TO BRING UP CICS." 
SAY 'IT"S EIGHT 0"CL0CK. TIME TO BRING UP CICS.' 
SAY 'PLEASE ENTER "GO NODENAME" OR "GO STOP"' 
SAY "PLEASE ENTER ""GO NODENAME"" OR ""GO STOP""" 

The first two instructions would both display the first line below, the last two 
instructions would both display the second line: 

IT'S EIGHT O'CLOCK. TIME TO BRING UP CICS. 
PLEASE ENTER "GO NODENAME" OR "GO STOP" 

Generally, you should enclose any NetView commands, or system commands 
recognized by NetView, in quotes. The exception is when you want variable substi- 
tution to take place on an operand of such a command. If you want variable substi- 
tution to take place, leave the operand outside of the quotes. 
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For example, if you want to use the NetView inact command in a command list to 
deactivate a node named nodei, you would code: 

'INACT NODEI' 

However, if the command list contains a variable named node and you want to 
deactivate the node whose name is the current value of the node variable, you 
would code: 

'INACT ' NODE 

The following is another example of using quotes to have rexx perform variable 
substitution on only part of a command: 

ARG DDNAME 

ADDRESS MVS 'EXECIO 1 DISKR ' DDNAME ' ( STEM LINE' 

This example would first parse the user's input into a variable called ddname. The 
tso/e execio command is then used to read a line of that ddname. address mvs is a 
rexx instruction, so it is not enclosed in quotes. The quotes begin before execio 
because it is a tso/e command. The quotes end before ddname to allow rexx to 
substitute the current value of the ddname variable into the execio command. The 
rest of the execio command is enclosed in quotes so that variable substitution does 
not take place on the stem and line operands. 

Suppressing Display of Non-REXX Commands 

Use the rexx trace command to control the suppression or echoing of non-REXX 
commands. The suppchar command of the nccfid statement does not influence the 
echoing of non-REXX commands. 

When issuing a command that returns its status in the return code, you can 
enhance the performance of your command list by suppressing synchronous output 
from the command. To suppress synchronous output, code the suppression char- 
acter defined on the nccfid statement twice. For example, if the suppression char- 
acter is defined as a question mark and you coded the following in a rexx 
command list: 

'??SET PF24 IMMED RETRIEVE' 

no synchronous output from the command is displayed to the operator. 

Use the double suppression character to enhance performance of commands that 
produce line mode messages synchronously and when sufficient status is provided 
by the return code. Using the double suppression character does not affect output 
that is scheduled by a command (for example, dnet.appls) nor does it reliably 
reduce output from a long running command (for example, nldm). 
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NetView Restrictions on REXX instructions 

This section describes the restrictions that apply when coding rexx instructions in 
rexx command lists for NetView. 

Pausing for Operator Input 

The rexx instructions parse ext, parse pull, pull, and trace ? cause a command list 
to pause for operator input. 

Using the parse ext or parse pull instructions along with other instructions, you can 
code command lists that ask the operator questions and pick up entered 
responses. Use the rexx say instruction to describe what the operator should 
enter. Code the parse ext or parse pull instruction after the say instruction to tem- 
porarily stop the command list (unless, in the case of parse pull, there is data on 
the data stack). After the command list has temporarily stopped, the operator must 
enter the NetView go command before it will continue. Any data to be passed to 
the command list must be entered as an operand or operands on the go command. 
For example, to have the command list process a yes or no answer from the oper- 
ator, you could code the following say and parse pull instructions: 

SAY 'ENTER "GO YES" OR "GO NO" TO CONTINUE' 
PARSE UPPER PULL ANSWER 

The operator could respond to the command list with either go yes or go no. The 
go command causes the command list to continue processing, and the yes or no 
value is picked up by the parse pull instruction. 

Using the SAY Instruction 

The rexx say instruction can have a character string of any length; however, 
NetView can output only 32,728 characters at a time. 

When you issue a rexx say instruction in a rexx command list for NetView, a 
12-character header precedes the data displayed on the operator's screen. The 
header contains the one-character NetView message type of the message 
(hdrmtypeo), followed by three blanks and the identifier of the domain under which 
the command list is running (applido). For more information on hdrmtypeo and 
applido, see Chapter 4, "REXX Functions Provided by NetView" on page 51. 

Do not use msgido as the first item of output from a say instruction because the 
message will be processed as a regular NetView message. This can cause the 
message to be trapped by a trap instruction and can incorrectly satisfy a wait 
instruction. 
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Using the CALL Instruction 

When you use the call instruction in rexx command lists for NetView, it is recom- 
mended that you enclose the command list you want to call within single quotes. 
You can call only rexx command lists with the call instruction. Any parameters to 
be passed to the called command list must be outside the quotes enclosing the 
name of the command list. If you want to avoid variable substitution for a param- 
eter, you must enclose the parameter in quotes. For example, if you code the fol- 
lowing call instruction to call an external command list named clist2: 

CALL 'CLIST2' PI, P2,' RESOURCE PU1 INACTIVE' 

and CLIST2 contained the following arg statement, 

ARG RES1 RES2 STATUS 

then the resi and RES2 variables are assigned the current values of pi and P2 when 
clist2 is called. 

If you execute clist2 as a command from another command list, for example: 

'CLIST2' PI, P2,' RESOURCE PU1 INACTIVE' 

then clist2 receives the same values for the variables on the arg statement, but the 
value of the argo function is set to 1 . 



NetView Restrictions on REXX Functions 

This section describes the restrictions that apply when coding rexx functions in 
rexx command lists for NetView. 

Note: Some rexx functions return different values depending on the operating 
system that the command list containing them is running under. For example, 
dateo returns the current date in different formats depending on the operating 
system. The rexx functions provided by NetView return the same values regard- 
less of the operating system. 

Using the REXX LINESIZE Function 

The rexx linesizeo function always returns the value 32,728 when used in rexx 
command lists for NetView. 

Using the REXX STORAGE Function 

rexx command lists for NetView cannot use the rexx storageo function. 



Using VM REXX Compression Tools 



NetView does not support the use of any vm rexx compression tools. If you experi- 
ence a problem with a command list that you compressed or optimized with a com- 
pression tool, test the same command list without using the tool before you report 
a problem to ibm. 
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Writing REXX Function Packages 



You can write your own rexx function packages for NetView. The NetView program 
supplies two dummy directories to help you write function packages. One directory 
is for a user function package (dsirxufp), and the other directory is for a local func- 
tion package (dsirxlfp). See REXX Reference for instructions on coding a real 
directory and coding the interface to your function code. Link-edit the real direc- 
tory and function code into load module dsirxufp for a user function package or 
dsirxlfp for a local function package. As part of coding the interface to your func- 
tion code, you need to use the NetView dsirxebs macro to obtain a new evalblock. 
See Customization: Using Assembler for information on the dsirxebs macro. 

See NetView Installation and Administration Guide and NetView Tuning Guide for 
information on improving the performance of rexx function packages for NetView. 



Changing the Environment Addressed by REXX Command Lists 

rexx command lists for NetView use NetView as the default addressing environ- 
ment. If you want to change the environment, use the rexx address instruction. 
For example, if you want your command list to execute mvs subcommands, you 
must first change the addressing environment with an address mvs instruction. 

In address mvs, you can use the following tso/e rexx commands: 

DELSTACK 

NEWSTACK 

QSTACK 

QBUF 

QELEM 

EXECIO 

MAKEBUF 

DROPBUF 

SUBCOM 

TS 

TE. 

See TSO/E REXX Reference for more information on these commands. 

Note: rexx command lists for NetView do not support address attach or address 
link. 



Using the TSO/E EXECIO Command 



If you use the tso/e rexx execio command in a command list, code the command list 
so that it issues an execio command with the finis option before the command list 
completes its processing. If the command list using execio is part of a nested chain 
of command lists, code the chain so that one of the command lists issues execio 
with the finis option before the chain of command lists completes processing. This 
enables you to use signal on halt to try to recover if execio with the finis option 
encounters an error closing a file. If the execio command encounters an error, it 
sets the rc variable to a non-zero return code. See TSO/E REXX Reference lor 
information on return codes used by the execio command. 
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See "TYPE Example" on page 58 and "PRINT Example" on page 60 for examples 
of how execio can be used in a rexx command list. 

Note: NetView running on a vm system does not support execio. 

Using the NetView ALLOCATE and FREE Commands 

The NetView program provides the allocate and free commands to enable you to 
dynamically allocate and deallocate data sets from NetView. NetView supports 
these commands on mvs systems only. The commands closely resemble the tso/e 
commands for allocating and deallocating data sets. However, because these 
commands are provided by the NetView program, you do not need to use the 
address mvs instruction when using these commands in a command list. Simply 
enclose the commands in quotes as you do for other NetView commands. The 
type, typeit, and print examples in Chapter 5, "Examples of REXX Command Lists 
for NetView" on page 57 use the NetView allocate command. See NetView Oper- 
ation for the syntax of the NetView allocate and free commands. 

Nesting REXX Command Lists from Assembler, C, or PL/I 

Each time a rexx command list is nested by an Assembler, c, or pl/i command 
processor, a unique rexx environment is created for that rexx command list. The 
data stacks from any previous rexx command lists in the nested chain are not 
passed to the additional unique environment. For example, if a rexx command list 
calls a pl/i command processor and the pl/i command processor calls another rexx 
command list, then an additional unique rexx environment is created for the 
second rexx command list. 

The number of unique rexx environments that can be created at one time is limited 
by tso/e rexx. Therefore, your nested chains are also limited in the number of rexx 
command lists that can be called by the Assembler, c, or pl/i command processors. 
See REXX Reference for information on the maximum number of environments in 
an address space. 



Parsing in REXX Command Lists 



In a rexx command list, you can parse character strings using either the rexx parse 
instruction or the NetView PARSEL2R command. 

See REXX Reference for information on the rexx parse instruction. 

See "Parsing Variables with PARSEL2R" on page 144 for information on using the 
NetView parsel2R command. When you use parsel2r in a rexx command list, 
enclose the command in quotes to avoid variable substitution. For example: 

TITLE = 'D0N"T TREAD (ROUGHLY) ON ME, PLEASE' 
'PARSEL2R TITLE Al A2 A3' 
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Tracing REXX Command Lists 



During the creation of a rexx command list for the NetView program, you can see 
how the rexx interpreter evaluates an expression using the trace start (ts) 
command. The ts command sets an indicator that is checked by the rexx inter- 
preter when it starts to interpret a command list or when control is returned to a 
command list after a nested command list completes execution. Figure 16 shows 
the syntax of the ts command. 



Figure 16. TS Command Syntax 

After receiving the following message on an mvs system: 

CNM431I REXX INTERACTIVE TRACE. ENTER 'GO TRACE OFF' TO END TRACE, 
ENTER 'GO' TO CONTINUE. 

or, after receiving the following message on a vm system: 

+++Interactive trace. TRACE OFF to end debug, ENTER to continue. +++ 

enter go to continue tracing, or enter go trace off to end the trace. Also, after 
receiving one of the messages indicating a trace point has been reached, you can 
enter go followed by a command or instruction you want to execute at that point in 
the command list. For example, to set a variable to a certain value at that point in 
the command list you could enter: 

GO X=5 

Or, to display the current value of a variable you could enter: 
GO SAY 'VAR1 CURRENTLY IS 'VAR1 

If you enter a ts command but decide that you do not want to run the trace before it 
begins, use the te command to cancel the trace. You can also use the te command 
to end a trace that is not interactive. Figure 17 shows the syntax of the te 
command. 



Figure 17. TE Command Syntax 

For more information on ts and te, see NetView Operation. 
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Return Codes in REXX Command Lists 



The rexx return code variable, rc, is set after execution of each instruction, 
command, or nested command list. You can use the exit statement in a nested 
command list to end the command list and set rc to a value that is passed back to 
the calling command list, rc is not given an initial value when a command list 
begins. 

Possible rc values and their meanings are: 

Values Meaning 

No error. The command, instruction, or nested command list 

completed successfully. 

-1 The command, instruction, or nested command list encountered 

an error. The -1 return code passes control to the failure label if 
signal on failure is coded. 

-3 The command or nested command list is not in the operator's 

scope of commands. The -3 return code passes control to the 
failure label if signal on failure is coded. 

-5 The command list has been canceled. The -5 return code passes 

control to the halt label if signal on halt is coded. 

Others Other return codes are set by individual commands, instructions, 

or nested command lists. 

Note: See "Recovering from Errors in REXX Command Lists" for more information 
on using the signal instruction with NetView. 



Recovering from Errors in REXX Command Lists 



When an error occurs in a rexx command list, you can use the signal instruction to 
cause processing to continue at a certain point. A command list can encounter an 
error for the following reasons: 

• An error exists in the coding of the command list itself. 

• The command list is part of a nested chain, and one of the other command lists 
in the chain contains an error that is passed back to the command list. 

• An operator enters a command that causes an error in the command list. 

If an error occurs, the signal instruction passes control to another part of the 
command list. Depending on the error condition, the signal instruction can pass 
control to three different labels in the command list: 

• signal on failure passes control to a label named failure when the error condi- 
tion results in a negative return code. The only negative return codes returned 
by NetView are -1 and —3. However, if your command list calls user written 
commands, control is passed to failure when any negative return code, except 
—5, is returned. 

If your command list recovers from the error, you can return the appropriate 
return code to the calling command list. If your command list does not recover 
from the error, pass the failure to the calling command list with exit -1. 

Note: Regardless of whether signal on failure is coded, NetView only passes 
the halt condition to the calling command list if you code exit -1. 
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signal on error passes control to a label named error when any command or 
function in your command list returns a positive return code. Control is also 
passed to error when signal on failure is not coded and a command or func- 
tion returns any negative return code except -5. 

The return code you pass to any command list that nested your command list 
should reflect the severity of the error. A zero (0) return code is recognized by 
all NetView commands as an indication of successful completion, while all pos- 
itive return codes indicate that an error occurred. The higher the return code, 
the greater the severity of the error. 

signal on halt passes control to a label named halt when the command list is 
canceled. A command list is canceled when: 

- A reset normal command is executed on the current operator task while 
your command list is running. 

- A close immed command is executed on any task in your NetView while 
your command list is running. The command list continues processing as 
long as it does not issue NetView commands. 

- During sna sessions, an operator presses the attn key while your 
command list is running. 

- A command issued by your command list is canceled or returns a return 
code of —5. 

- The operator's terminal session is lost for any reason, including the oper- 
ator entering the logoff command, while the command list is running. The 
command list continues processing as long as it does not issue NetView 
commands. 

To pass the halt condition to any command list that nested your command list, 
end the command list with exit -5. 

Notes: 

1. If you do not code signal on halt, NetView passes the halt condition to the 
command list that nested your command list. 

2. Whenever you call another rexx command list as a function or subroutine, 
the following statement of the command list should test the result variable 
for the -5 cancel condition. 

For more information on the signal instruction, see REXX Reference. 
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Chapter 3. REXX Instructions Provided by NetView 

This chapter describes the instructions used in rexx command lists for NetView. 
These instructions are provided as part of the NetView program so rexx command 
lists can perform specific NetView activities. Because these instructions are pro- 
vided by NetView and are not standard rexx instructions, they can only be used in 
command lists that execute in a NetView environment. These instructions do not 
function in any rexx execs that are executing in non-NetView environments. The 
instructions provided by NetView are internal commands, which means they can 
only be used in command lists, and are not available for entry at operator con- 
soles. 

This chapter contains a description of each rexx instruction provided by the 
NetView program, how the instruction works, and how to code the instruction in a 
rexx command list. For more information on rexx syntax rules, as well as informa- 
tion on other rexx instructions, see REXX User's Guide or REXX Reference. 

See Appendix C, "Comparison of REXX and NetView Command List Language" on 
page 185 for a complete list of the rexx instructions that are equivalent to NetView 
command list language control statements. This list includes both instructions pro- 
vided by NetView and instructions provided by rexx itself. See "Examples Com- 
paring REXX and NetView Command List Language" on page 193 for examples of 
command lists written in the NetView command list language and the equivalent 
rexx command lists. 

The rexx instructions provided by the NetView program are: 

TRAP 

WAIT 

WAIT CONTINUE 

MSGREAD 

FLUSHQ 

GLOBALV. 

The trap, wait, wait continue, and msgread instructions are used in a command list 
to monitor the operator station task (ost) for specific messages or wait for a speci- 
fied period of time. 

You can use the trap instruction to define the messages for which the command 
list should wait. When a trap instruction is issued, NetView begins monitoring the 
operator task for an occurrence of a specified message. If the message is 
received, it is stored in a message queue. 

When a wait instruction is issued, the command list stops processing until one or 
more of the messages specified on the trap instruction are received or until the 
specified period of time has elapsed. 

The wait continue instruction causes the command list to wait for additional mes- 
sages or the remainder of the specified period of time before resuming command 
list processing. 

If the operator task receives any of the messages specified on a trap instruction, 
you can use the msgread instruction to read the trapped messages from the 
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message queue. The command list can then take action based on the content of 
each message. 

The flushq instruction is used to remove ail trapped messages from the message 
queue. 

"Sample Command List Using TRAP, WAIT, MSGREAD, and WAIT CONTINUE" on 
page 42 contains a command list that shows how the trap, wait, msgread, and wait 
continue instructions are used. 

The globalv instruction allows you to set and retrieve task and common global var- 
iables in rexx command lists. "Examples of Command Lists that Set, Retrieve, and 
Update Task Global Variables" on page 47 contains two command lists that show 
how the globalv instruction is used. 



REXX TRAP Instruction 



Use the trap instruction to define messages that are to be trapped and to specify 
whether the messages should be displayed to the operator once they are trapped. 
The trap instruction can also be used to remove all messages from the list of mes- 
sages to be trapped. 

The trap instruction causes NetView to monitor the operator task for specified 
messages. If the messages occur, they are trapped and added to the message 
queue. Trapped messages can then be read using the msgread instruction and can 
satisfy a wait instruction. See "REXX MSGREAD Instruction" on page 40 and 
"REXX WAIT Instruction" on page 36 for information on how these instructions are 
used with the trap instruction. 

The trap instruction does not clear the queue of messages trapped by the previous 
trap. To clear the message queue, issue a flushq instruction. See "REXX 
FLUSHQ Instruction" on page 42 for more information on flushq. 

Figure 18 shows the syntax of the trap instruction. 

Notes: 

1. The operands must be entered in the order shown in Figure 18. 

2. The instruction is enclosed in single quotes to prevent variable substitution by 

REXX. 



• TRAP [[AND 1SUPPRESSI DISPLAY1 
[MORE|ONLY] 
MESSAGES token [,...]• 

OR 

TRAP NO MESSAGES' 

Figure 18. TRAP Instruction Syntax 
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AND 

can be used to make the trap instruction syntax more readable, and can only 
be used between trap and suppress or trap and display. 

SUPPRESS ID1SPLAY 

SUPPRESS indicates that any messages matching the specified tokens 

should not be displayed on the operator's screen when received 
by NetView. 



DISPLAY 



MORE IONLY 
MORE 



ONLY 



indicates that any messages matching the specified tokens 
should be displayed on the operator's screen when received by 
NetView. 



indicates that the specified tokens should be added to the list of 
tokens that was specified on a previous trap instruction. 

Note: Each message in the resulting list retains its own individual 
setting of the suppress|display option. This allows some messages 
in the list to be suppressed while others are displayed. 

indicates that the specified tokens replace the list of tokens speci- 
fied on a previous trap instruction. 



MESSAGES 

indicates that the trapped items are messages. 

token [,...] 

1 to 10 characters that identify the first token of the message or messages to be 
trapped. Optionally, you can identify the domain of a message to be trapped. 
If a domain identifier is specified, it precedes the token and is separated from 
the token by a period {domainid.token). You can also use an asterisk (*) to 
indicate that you are specifying a partial domain identifier or token. If you do 
not specify a domain identifier, the message being trapped can be from any 
domain. 

Note: If you specify suppress and use an asterisk when specifying a domain 
identifier or token, no messages matching the specified domain or token will 
be displayed to the operator. For example, if you have a command list that 
traps and suppresses all messages, no rexx messages are displayed to the 
operator when the command list is run. This includes any rexx trace output 
and messages if you are using the rexx trace instruction to debug the 
command list. 

Following are examples of how you can specify the messages you want to trap: 

domainid.token The command list traps any message whose domain identi- 
fier matches the 1- to 5-character domainid and whose first 
token matches token. 



dom*.token 



.token 



The command list traps any message whose domain identi- 
fier matches the partial domain identifier specified by dom* 
and whose first token matches token. For example, 
nccf*.dsi463I means trap a DSI463I message from any domain 
with an identifier that starts with nccf (such as nccfa or 

NCCFB). 

The command list traps any message whose first token 
matches token. The message can be from any domain. 
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NO 



token The command list traps any message whose first token 

matches token. The message can be from any domain. 

tok* The command list traps any message whose first token 

matches the partial token specified by tok*. For example, 
dsi* means trap any messages whose first token begins with 

DSI (SUCh as DSI463I Or DSI386I). 

* The command list traps ail messages. 

Note: Use caution when coding * or V with suppress. This 
causes no messages to be displayed to the operator. 

Multi-line messages such as multi-line-write-to-operator (mlwto) are treated as 
one message. Therefore, only the message identifier of the first message in a 
multi-line message is available to the trap, and the trap can be satisfied only 
by that message identifier. Use getmsize, getmtype, and getmline to access the 
other messages in a multi-line message. See "Working with Multi-Line 
Messages" on page 151 for more information on multi-line messages. 

indicates that NetView should stop trapping the messages that were specified 
on the previous trap instruction. 



trap sets the value of rc to indicate the processing results, as follows: 

Code Meaning 

Successful completion 

4 trap only allowed from hll or rexx command lists 

12 Syntax error 

144 Not in ost or nnt 

18004 dsimrbld invalid parameter 

18008 dsimrbld storage failure. 

A sample command list, showing how the trap instruction can be used, appears in 
"Sample Command List Using TRAP, WAIT, MSGREAD, and WAIT CONTINUE" on 
page 42. Also, several of the examples in Chapter 5, "Examples of REXX 
Command Lists for NetView" on page 57 use trap, wait, and msgread. 

Using TRAP in Nested REXX Command Lists 

You can code a trap instruction in a rexx command list that contains nested 
command lists. Nested rexx command lists can also contain a trap instruction. 
However, trapped messages are available only to the command list that issued the 
trap instruction. 



REXX WAIT Instruction 

The wait instruction causes a command list to temporarily suspend processing 
until a specified event occurs. The event can be one or more messages, a certain 
period of time, or both. The first event that occurs satisfies the wait 

Note: There are times when you cannot use wait. Before coding wait, read 
"Primary POI Task Restrictions" on page 17. Do not code wait with service point 
service commands. For additional information, see Chapter 10, "Service Point 
Command Service Commands" on page 165. 

Figure 19 on page 37 shows the syntax of the wait instruction. 
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Notes: 

1. The operands must be entered in the order shown in Figure 19 on page 37. 

2. You must code a time interval (n seconds or n minutes), messages, or both. 

3. The instruction is enclosed in single quotes to prevent variable substitution by 

REXX. 



j 'WAIT in rSECONDS IMINUTESn 

j [FOR [MESSAGES]]' 

Figure 19. WAIT Instruction Syntax 



means the command list waits n seconds or minutes before resuming command 
list processing. 

When seconds is specified, the value of n can be from to 2,678,400. When 
minutes is specified, the value of n can be from to 44,640. The equivalent of 
2,678,400 seconds or 44,640 minutes is 31 days. 

SECONDSI MINUTES 

SECONDS means the command list waits n seconds before resuming proc- 
essing. 

MINUTES means the command list waits n minutes before resuming proc- 
essing. 

FOR 

can be used to make the wait instruction syntax more readable. 

MESSAGES 

means the command list waits for a trapped message to be added to the 
message queue before resuming processing. The specific messages for which 
the command list should wait are defined using the trap instruction. If a time 
interval is also specified, the command list waits for up to that amount of time 
and then resumes even if one of the specified messages has not been 
received. If one of the specified messages is already on the message queue, 
the command list resumes without waiting. See "REXX TRAP Instruction" on 
page 34. 

When NetView encounters a wait instruction in a rexx command list, the letter w is 
displayed in the upper right-hand corner of the current command facility panel if 
the screen is refreshed as the result of a message being received or the enter key 
being pressed. This notifies the operator that the command list has halted its proc- 
essing and is waiting for a message or group of messages or for a specific period 
of time. The first event that occurs satisfies the wait. 
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Checking the Result of a WAIT Instruction 

The NetView event that satisfied the wait is determined by the value of the rexx 
eventq function. The rexx command list can check evento and take appropriate 
action based on its value. The possible values for evento are: 

M The message the command list is waiting for has arrived. The message can 
be read using the msgread instruction. 

T The time period for which the command list was waiting has expired, and 
processing is resumed. 

G The operator entered the go command, and processing is resumed. 

E The wait or trap instructions were not coded correctly. For example, the 
operands were not entered in the correct order or a wait instruction was 
issued without a matching trap instruction. The command list resumes proc- 
essing. 

If a wait instruction is never issued in a command list, the value of the evento func- 
tion is set to null. 

wait sets the value of rc to indicate the results of processing, as follows: 

Code Meaning 

-1 dsiget failure 

Successful completion 

4 wait only allowed from hll or rexx command lists 

8 Too many operands 

12 Syntax error 

144 Not in OST or nnt 

152 wait issued without a previous trap 

248 wait continue issued without a previous valid wait. 

A command list, showing how the wait instruction can be used, appears in 
"Sample Command List Using TRAP, WAIT, MSGREAD, and WAIT CONTINUE" on 
page 42. Also, several of the examples in Chapter 5, "Examples of REXX 
Command Lists for NetView" on page 57 use trap, wait, and msgread. 

Continuing to Wait for Additional Messages 

You can code a wait continue instruction in your rexx command list to cause the 
command list to continue waiting before resuming command list processing. 

Figure 20 shows the syntax of the wait continue instruction. 

Note: The instruction is enclosed in single quotes to prevent variable substitution 
by rexx. 



WAIT CONTINUE 1 § 

Figure 20. WAIT CONTINUE Instruction Syntax 

The options specified on the previous trap arid wait instructions remain in effect for 
the wait continue instruction. When processing resumes, the next instruction after 
the wait continue is executed. 
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For example, if you code the following instructions in a command list and one of 
the messages specified on the trap instruction is received in 5 seconds: 

'TRAP AND SUPPRESS MESSAGES MSG1, MSG2, MSG3' 

'WAIT 2G SECONDS FOR MESSAGES' 

'MSGREAD' 



'WAIT CONTINUE' 
'MSGREAD' 

then the wait instruction is satisfied. The wait continue instruction waits up to 15 
seconds (the difference between the 20 seconds specified on the wait instruction 
and the 5 seconds already used to satisfy the wait instruction) to receive one of the 
messages specified on the trap instruction before resuming command list proc- 
essing. When processing resumes, the msgread instruction following wait continue 
is executed. 

A sample command, showing how the wait continue instruction is used, appears in 
"Sample Command List Using TRAP, WAIT, MSGREAD, and WAIT CONTINUE" on 
page 42. Also, several of the examples in Chapter 5, "Examples of REXX 
Command Lists for NetView" on page 57 contain examples of command lists that 
use wait continue. 

Using NetView Commands with WAIT 

When a rexx command list is in a wait or pause state, operator commands that are 
entered can be deferred. Whether the commands are deferred is based on the 
NetView defaults, override, and cmd commands. See NetView Operation for infor- 
mation on these commands. 

The go, stack, unstack, and reset commands affect the processing of command 
lists in a wait state as follows: 

• go ends a wait. 

• stack suspends command list processing and causes any commands that have 
been deferred to be processed. You can enter any command or command list 
for normal processing while a command list is suspended. The wait is not sus- 
pended, and events are still matched as they occur. The w, if present, does not 
remain in the upper right corner of the NetView screen. The go command is 
rejected until the command list resumes processing. 

• unstack resumes command list processing. The wait resumes processing 
events that were matched while the command list was suspended. The wait 
does not resume after expiration of a specified period of time if, while the 
command list was suspended, you ran another command list that issues a wait 
or &wait with a specified period of time. 

• reset ends a command list, as well as all command lists related to it by 
nesting, reset also drives halt when signal on halt is coded. 

For more information on the go, stack, unstack, and reset commands, see NetView 
Operation. 
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Using WAIT in Nested Command Lists 

rexx command lists that call other command lists or are called by other command 
lists can issue a wait instruction. The following considerations apply when using 
wait with nested command lists: 

• Messages that arrive for the waiting command list are queued until the nested 
command list has finished processing. 

• If you specify the same message number on trap instructions in both the 
waiting and nested command lists, the message satisfies the wait in the nested 
command list. 



REXX MSGREAD Instruction 



The msgreao instruction causes NetView to read a trapped message from the 
message queue. The command list can then take action based on the message. 
See "REXX TRAP Instruction" on page 34 and "REXX WAIT Instruction" on 
page 36 for information on how these instructions are used with the msgread 
instruction. 

When a msgreao instruction is issued, the oldest message in the queue is read and 
removed from the queue. The message that is read is used to set msgid(), 
msgcnt(), msgorign(), and msgstr(). The message text is used to set the parameter 
variables msgvar(1) - msgvar(31). See "Functions Set by MSGREAD" for information 
about the variables set by msgreao. 

Figure 21 shows the syntax of the msgread instruction. 

Note: The instruction is enclosed in single quotes to prevent variable substitution 
by rexx. 



MSGREAO' 

Figure 21. MSGREAD Instruction Syntax 

msgread sets the value of rc to indicate the results of processing, as follows: 



Code 


Meaning 


-2 


Syntax error 


-1 


dsiget failure 





Successful completion 


4 


No messages in queue. 



A sample command list, showing how the msgread instruction is used, appears in 
"Sample Command List Using TRAP, WAIT, MSGREAD, and WAIT CONTINUE" on 
page 42. Also, several of the examples in Chapter 5, "Examples of REXX 
Command Lists for NetView" on page 57 use trap, wait, and msgread. 

Functions Set by MSGREAD 

NetView sets the values of the msgcnto, msgido, msgorigno, msgstrq, msgtypo, and 
msgvar(h) functions based on the information contained in a message read by a 
msgread instruction. 

MSGCNTQ 

becomes the number of elements in the text of msgstro. 
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MSGID() 

becomes the message identifier of the last message read. The message iden- 
tifier is the first token of the message (up to 10 characters). If the first token is 
longer than 10 characters, msgido uses only the first 10 characters. 

MSGORIGNO 

becomes the name of the domain from which the message was sent. 

MSGSTRO 

becomes the message text exactly as it is received by NetView. msgstro does 
not include the message identifier (the token used by the msgido function). 

MSGTYPO 

becomes the system message type of the last message read. 

MSGVAR(n) 

NetView changes the values of the msgvar(1) - msgvar(31) functions to reflect the 
text of the message. Each msgvarm function is set to a token of the message. 
Tokens are delimited by commas, apostrophes, or blanks. msgvar(1) is set to 
the first token following the message identifier (the token used by the msgido 
function). msgvar(2) is set to the next token to the right of msgvar(1), and so on 
up to a maximum of 31 variables. 

For example, if msgread is used to read the following message: 
DSI008I SPAN1 NOT ACTIVE 
the functions are set as follows: 



Variable 


Value 


MSGORIGNO 

MSGIDO 

MSGSTRO 


DOM01 
DSI008I 
SPAN1 NOT ACTIVE 


MSGCNT() 
MSGVAR(1) 
MSGVAR(2) 
MSGVAR(3) 


3 

SPAN1 
NOT 
ACTIVE 


MSG VAR(4)-MSGVAR(31 ) 


null 



Notes: 

1. If msgread reads a a multi-line message, the functions are set according to the 
first line of the message. See "Working with Multi-Line Messages" on 

page 151 for information concerning working with multi-line messages. 

2. The msgvar(1) - msgvar(31) functions can be given values when a command list 
is invoked in the same way the &1 - &31 NetView command list language 
parameter variables can. (See "Parameter Variables" on page 77.) If 
msgvar(I) - msgvar(31) are given values when the command list is invoked, save 
those values in variables before issuing a msgread instruction. This lets you 
use the values after msgread changes them. 

3. After using msgread, save the values of the message functions in variables 
before issuing another msgread instruction. This lets you use the values after 
another msgread changes them. 

4. Before a msgread instruction is issued, the values of msgido. msgorigno, 
msgstro, and msgtypo are null. The value of msgcnto is 0. The msgvar(/j) func- 
tions retain any values they were given when the command list was run. 

5. If you issue a msgread instruction when the message queue is empty, the 
values of msgido, msgorigno, msgstro, msgtypo, and msgvar(/?) are set to null. 
The value of msgcnto is 0. 
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REXX FLUSHQ Instruction 



The flushq instruction is used to remove all trapped messages from the message 
queue, including the message currently being processed. 

Figure 22 shows the syntax of the flushq instruction. 

Note: The instruction is enclosed in single quotes to prevent variable substitution 
by rexx. 



'FLUSHQ [MESSAGES]' 

Figure 22. FLUSHQ Instruction Syntax 

Because the trap instruction does not clear the queue of messages trapped by a 
previous trap, you should issue a flushq instruction between multiple trap 
instructions coded in the same command list. 

flushq sets the value of rc to indicate the results of processing, as follows: 

Code Meaning 

-1 Syntax error 

Successful completion. 

Sample Command List Using TRAP, WAIT, MSGREAD, and WAIT 
CONTINUE 

This section contains an example of a command list that illustrates how the trap, 
wait, msgread, and wait continue instructions can be used in rexx command lists. 

Figure 23 is a rexx command list named actlu. actlu issues a vtam command to 
activate a node specified by the user. Messages sent as the result of the activate 
command are trapped, and the operator is notified of the result of the command 
list. The comments in the example explain how the command list works. 



/* ACTLU COMMAND LIST */ I 

/* V 1 

/* FUNCTION : TO ACTIVATE A VTAM NODE. */ I 

/* INPUT : 1 PARAMETER, THE NAME OF THE NODE. */ 1 

/••A*************************************************** h 

IF MSGVAR(l) = " THEN /* NO FIRST PARAMETER ? • */ j 

DO /* THEN ISSUE REQUEST */ 1 

SAY 'PLEASE ENTER "GO NGDENAME M \ /* REQUEST NODENAME FROM USER */ J 

'TO CONTINUE OR "GO STOP" TO', /* OR, ALLOW USER TO STOP */ | 

'STOP' 

PARSE PULL NODE /* NODE = NODENAME OR STOP */ 1 

END /*• THEN ISSUE REQUEST */ j 

ELSE /* FIRST PARAMETER EXISTS */ | 

NODE = MSGVAR(l) /* ASSUME IT IS A NODE NAME */ J 

Figure 23 (Part 1 of 2). Sample Command List Using TRAP, WAIT, MSGREAD, and WAIT 
CONTINUE 
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I IF N0DE-,='ST0P' THEN /* IF USER DID NOT CHOOSE STOP */ 

■■ DO /* PROCESS NODENAME */ 

I 'TRAP AND SUPPRESS ONLY MESSAGES 1ST* • /* TRAP ALL VTAM MSGS */ 

'V NET,ACT,ID='NODE /* ISSUE VTAM ACTIVATE FOR NODE */ 

!■' RCSAVE=RC /* SAVE RETURN CODE IN RCSAVE */ 

'WAIT 30 SECONDS FOR MESSAGES' /* WAIT FOR 30 SECONDS */ 

SELECT 

\ WHEN <EVENT()='M') THEN /* OUT OF WAIT - IS THERE A MSG? */ 

DO /* PROCESS TRAPPED MESSAGE */ 

! 'MSGREAD' /* READ IN 1ST MESSAGE */ 

!'- DO WHILE (RC=0) /* IF RC-=0 THEN NO MORE MSGS */ 

! SELECT /* DETERMINE WHICH MESSAGE HIT */ 

I WHEN (MSGIDO * 'IST061I') /* NODE NOT FOUND */ 

THEN SAY '==> LU UNKNOWN', /* INFORM USER */ 

i 'TO YOUR VTAM <=' 

): WHEN (MSGIDO = 'IST093I') /* NODE NOW ACTIVE */ 

i THEN SAY '==> TERMINAL', /* INFORM USER */ 

\i. .. .. MSGVAR(l)' NOW', 

1 MSGVAR(2) '<==' 

OTHERWISE /* IGNORE THE VTAM MESSAGE */ 
IF RCSAVE=0 THEN 

'WAIT CONTINUE' /* CONTINUE WAITING */ 
ELSE DO 

SAY 'ERROR PROCESSING', /* ERROR ENCOUNTERED ? */ 

•ACTIVATE COMMAND' /* INFORM USER */ 

SAY MSGSTR() /* DISPLAY MESSAGE TEXT */ ' 

END 

END /* OF SELECT FOR IST061I/IST093I */ 

'MSGREAD' /* READ IN THE NEXT MESSAGE */ 

* END /* DO WHILE RC=0, LOOP BACK */ 

END /* PROCESS TRAPPED MESSAGE DO */ 

/* OUT OF DO WHILE */ 

WHEN (EVENT()='E'|SAVERC-«=0) THEN /* CHECK FOR ERROR OR */ 

l /* TIMEOUT EVENTS */ 

i SAY 'ERROR PROCESSING', /* ERROR ENCOUNTERED? */ 

I 'ACTIVATE COMMAND' /* INFORM USER */ 

t WHEN (EVENT()='T') THEN /* WAIT TIMEOUT ENCOUNTERED ? */ 

SAY 'NO RESPONSE TO', /* INFORM USER */ 

'ACTLU CLIST FOR 'NODE 

OTHERWISE /* NO-OP */ 

END /* OF SELECT FOR ERROR/TIMEOUT */ 

END /* IF NODE--' STOP' PROCESSING */ 

Figure 23 (Part 2 of 2). Sample Command List Using TRAP, WAIT, MSGREAD, and WAIT 
CONTINUE 
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REXX GLOBALV Instruction 



The rexx globalv instruction allows you to set and retrieve global variables in rexx 
command lists. Global variables allow multiple command lists, regardless of their 
language, to share a common set of values. There are two types of global vari- 
ables: task and common. Task global variables let you set and retrieve any 
number of global variables in command lists running under a particular NetView 
task. Common global variables let you set and retrieve global variables in 
command lists running under any NetView task. 

When you set a global variable using the globalv instruction, NetView places that 
variable in a global variable dictionary. If the variable is a task global variable, it 
is stored in the global variable dictionary for the particular task under which the 
command list is running. Only command lists running under the same task can 
access that task's global variable dictionary. 

When you want to use a global variable in a command list, the globalv instruction 
retrieves the global variable from the appropriate dictionary and places it in a rexx 
variable of the same name. You can then perform arithmetic operations or other 
manipulations on the rexx variable to suit the needs of your command list without 
affecting the value of the global variable in the dictionary. 

Command lists written in the NetView command list language use the &cglobal 
and &tglobal control statements to access global variables. 

When setting global variables using the globalv instruction, follow these guide- 
lines: 

• The global variable name can be 1 to 31 alphanumeric characters. Valid 
alphanumeric characters are A-Z, 0-9, #, @, 0, $,_,!, ?, and period (.). The first 
character cannot be a number or a period (.). 

Note: The NetView command list language does not allow variable names to 
contain a period, _, c\ !, or ? and limits global variables to a length of 11 char- 
acters. Therefore, if you want global variables you create in a rexx command 
list to also be accessible to command lists written in the NetView command list 
language, make sure the global variable names are from 1 to 11 characters in 
length and do not contain a period, _, 0, !, or ?. 

• If more than one global variable is specified on the globalv instruction, the 
variable names must be delimited by commas or blanks. 

• The value of the global variable can be 255 characters long. For double-byte 
character sets the maximum number of double-byte characters between the 
shift-out and shift-in is 126. 

• You can give global variables a numerical value between -2147483647 and 
2147483647. 

See "Scope of Variables in Command Lists" on page 127 for information about the 
scope of global variables in command lists. 
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Setting Task Global Variables in REXX Command Lists 

To set a task global variable from a rexx command list, use the globalv putt 
Instruction. The globalv putt instruction creates a task global variable with the 
specified variable name and places it in the task global variable dictionary for the 
task under which the command list is running. 

Figure 24 shows how to code a globalv instruction to set a task global variable. 

Note: The instruction is enclosed in single quotes to prevent variable substitution 
by rexx. 



GLOBALV PUTT variable [,...]' 

Figure 24. GLOBALV PUTT Instruction Syntax 

PUTT 

indicates that task global variables with the specified variable names should 
be set. 

variable [,...] 

the 1- to 31-character names of the task global variables to be set. See page 
44 for a list of the characters that can be used for a variable name. 

When a globalv putt instruction is processed, the NetView program determines 
whether a rexx variable already exists with the specified variable name. If a rexx 
variable with the same name exists, the task global variable is created, and its 
value is set to the value currently assigned to the rexx variable. 

If no rexx variable exists with the variable name specified, a task global variable 
with that name is created. The value of the task global variable is set to null. 

If a task global variable already exists with the specified variable name, the value 
of the task global variable is updated in the task global dictionary. 

The command lists in "Examples of Command Lists that Set, Retrieve, and Update 
Task Global Variables" on page 47 show how to set, retrieve, and update a task 
global variable. 
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Retrieving Task Global Variables in REXX Command Lists 

To access a task global variable in a rexx command list, use the globalv gett 
instruction. The globalv gett instruction retrieves the value of the specified task 
global variable and assigns it to a rexx variable of the same name. 

Figure 25 shows how to code a globalv instruction to retrieve a task global vari- 
able. 

Note: The instruction is enclosed in single quotes to prevent variable substitution 
by rexx. 



' GLOBALV GETT variable [,...] » j 

Figure 25. GLOBALV GETT Instruction Syntax 

GETT 

indicates that the task global variables with the specified variable names 
should be retrieved. 

variable [,...] 

the 1- to 31-character names of the task global variables to be retrieved. 

When a globalv gett instruction is processed, the NetView program retrieves the 
current value of the specified task global variable from the task global variable dic- 
tionary and places it in a rexx variable of the same name. If a rexx variable with 
the same name does not already exist, the rexx variable is created, and its value is 
set to the current value of the task global variable. 

If no task global variable with the specified variable name exists, the value of the 
rexx variable is set to null. 

The command lists in "Examples of Command Lists that Set, Retrieve, and Update 
Task Global Variables" on page 47 show how to set, retrieve, and update a task 
global variable. 
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Examples of Command Lists that Set, Retrieve, and Update Task Global 
Variables 

Figure 26 and Figure 27 are examples of rexx command lists that show how to set, 
retrieve, and update a task global variable. The first command list is named 
initializer and it executes the nested command list updatel 



!/* INITIALIZE! COMMAND LIST */ 

j ./* THE FOLLOWING ASSIGNMENT STATEMENT GIVES THE REXX 

I VARIABLE, TOM, A VALUE OF 5. .*./ 

I TOM = '5' 

f /* THE FOLLOWING STATEMENT SETS A TASK GLOBAL VARIABLE 

I NAMED TOM. THE VALUE OF TASK GLOBAL VARIABLE TOM IS 5 

I BECAUSE THE VALUE OF REXX VARIABLE TOM IS 5. */ 

I 'GLOBALV PUTT TOM' 

I J* THE FOLLOWING STATEMENT EXECUTES A NESTED COMMAND LIST NAMED 

f. UPDATE1. */ 

lUPDATEl ■.:,.'.■■■■" ■■ ■/:■:;■,;.■ : ' 

f /* THE FOLLOWING STATEMENT RETRIEVES THE VALUE OF TASK 

I GLOBAL VARIABLE TOM AND PLACES IT IN A REXX 

l VARIABLE NAMED TOM. */ 

I 'GLOBALV GETT TOM* 

I :/* THE FOLLOWING STATEMENT WILL WRITE THE VALUE OF THE 

I REXX VARIABLE TOM. */ 

t SAY 'TOM * 'TOM 

\. EXIT . • •; • x: 

Figure 26. INITIALIZE1 Command List 



£/* UPDATE 1 COMMAND LIST */ 

|/* THE FOLLOWING STATEMENT RETRIEVES THE VALUE OF TASK 

I GLOBAL VARIABLE TOM INTO A REXX VARIABLE NAMED 

r TOM. */ ' ' rl'^x-x:--. 

\ 'GLOBALV GEH TOM' 

\ I* THE FOLLOWING STATEMENT CHECKS THE VALUE OF REXX 

I VARIABLE TOM TO DETERMINE IF IT IS NULL. */ 

£ IF TOM -■" THEN TOM = $ 

r /* THE FOLLOWING STATEMENT INCREMENTS REXX VARIABLE 

V TOM BY 1. */ 

; TOM = TOM + 1 

}./* THE FOLLOWING STATEMENT SETS THE VALUE OF TASK 

| GLOBAL VARIABLE TOM */ 

| 'GLOBALV PUTT TOM' 

! EXIT 

Figure 27. UPDATE1 Command List 

Command list initializei creates a rexx variable called tom and gives it a value of 
5. A globalv putt instruction is issued to set a task global variable named tom. 
Since a rexx variable with the name tom already exists with a value of 5, the value 
of task global variable tom is also set to 5. initializei activates a nested command 
list named updatel 
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Command list updatei issues a globalvgett instruction to retrieve the current 
value of task global variable tom into a rexx variable named tom. The value of 
rexx variable tom is checked to determine if it is null. If the value is null, its value 
must be set to 0. Because the current value of rexx variable tom is 5, it is incre- 
mented by 1, making its current value 6. The globalv putt instruction causes the 
value of task global variable tom to be updated in the task global variable dic- 
tionary. 

When updatei completes execution, control is returned to the initializei command 
list, initializei contains a globalv gett instruction to retrieve the current value of 
task global variable tom and place it in a rexx variable named tom. The value of 
rexx variable tom is 6 because the current value of task global variable tom is 6. 
The say instruction displays the current value of the rexx variable tom. 

Setting Common Global Variables in REXX Command Lists 

To set a common global variable in a rexx command list, use the globalv putc 
instruction. The globalv putc instruction creates a common global variable with 
the specified variable name and places it in the common global variable dictionary. 

Figure 28 shows how to code a globalv instruction to set a common global vari- 
able. 

Note: The instruction is enclosed in single quotes to prevent variable substitution 
by rexx. 



'GLOBALV PUTC variable [,...]' 

Figure 28. GLOBALV PUTC Instruction Syntax 

PUTC 

indicates that common global variables with the specified variable names 
should be set. 

variable [,...] 

the 1- to 31-character names of the common global variables to be set. See 
page 44 for a list of the characters that can be used for a variable name. 

When a globalv putc instruction is processed, the NetView program determines if 
a rexx variable already exists with the specified variable name, if a rexx variable 
with the same name already exists, the common global variable is created, and its 
value is set to the value currently assigned to the rexx variable. 

If no rexx variable exists with the variable name specified, a common global vari- 
able with that name is created. The value of the common global variable is set to 
null. 

if a common global variable already exists with the specified variable name, the 
value of the common global variable is updated in the common global dictionary. 

Note: Be careful if you have more than one command list running under different 
tasks and accessing the same global variable. The last value that the variable is 
set to is the value that is retrieved by any command list accessing the variable. 
For example, a command list accesses a common global variable and then before 
that command list updates the variable, another command list running under a dif- 
ferent task accesses the variable. If both command lists update the variable, the 
variable assumes the value given to it by the command list that updates it last. To 
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avoid having a common global variable being used by different command lists at 
the same time, you should have all command lists that use the variable run under 
the same task. 

You can use the NetView-supplied command lists updcglob and setcglob to update 
and set common global variables under the ppt. See NetView Operation for infor- 
mation on using updcglob and setcglob. 

See "CHKOPNUM Example" on page 62 and "CHKRSTAT Example" on page 64 
for examples of how to set common global variables. 

Retrieving Common Global Variables in REXX Command Lists 

To access a common global variable in a rexx command list, use the globalv getc 
instruction. The globalv getc instruction retrieves the value of the specified 
common global variable and assigns it to a local rexx variable of the same name. 

Figure 29 shows how to code a globalv instruction to retrieve a common global 
variable. 

Note: The instruction is enclosed in single quotes to prevent variable substitution 
by rexx. 



'GLOBALV GETC variable [,...]* 

Figure 29. GLOBALV GETC Instruction Syntax 

GETC 

indicates that common global variables with the specified variable names 
should be retrieved. 

variable [,...] 

the 1- to 31 -character names of the common global variables to be retrieved. 

When a globalv getc instruction is processed, the NetView program retrieves the 
current value of the specified common global variable from the common global 
variable dictionary and places it in a rexx variable of the same name. If a rexx 
variable with the same name does not already exist, the rexx variable is created, 
and its value is set to the value currently assigned to the global variable. 

If no common global variable with the specified variable name exists, the value of 
the rexx variable is set to null. 

See "CHKOPNUM Example" on page 62, "CHKRSTAT Example" on page 64, and 
"DSPRSTAT Example" on page 66 for examples of how to retrieve common global 
variables. 
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Chapter 4. REXX Functions Provided by NetView 

This chapter describes the functions used in rexx command lists for NetView. 
These functions are provided as part of the NetView program so that command 
lists written in rexx can perform specific NetView activities. Because these func- 
tions are provided by NetView and are not standard rexx functions, they can only 
be used in command lists that execute in a NetView environment. These functions 
do not execute in any rexx execs that are executing in non-NetView environments. 

Note: You can improve the performance of your rexx command list by limiting the 
use of rexx functions provided by NetView. If the same function, provided by 
NetView, is used several times in the command list without a change in value, use 
the function once to set a local variable to the value of the function. After setting 
the rexx function provided by NetView to a local variable, use the local variable in 
place of the function. If the value of the function changes during execution of the 
command list, you need to use the function each time to access its current value. 
For more information on setting rexx variables, see "REXX GLOBALV Instruction" 
on page 44. 

Included in this chapter is a description of each function provided by NetView, how 
it works and how to code the instruction in a rexx command list. For more informa- 
tion on rexx syntax rules, as well as information on other rexx functions, see REXX 
User's Guide or REXX Reference. 

The functions provided by the NetView program are set based on system informa- 
tion. To use a function, you must place the function name in the rexx command list 
at the location where you want the information to be accessed. When the 
command list runs, NetView gives the correct values to each function. 

The functions let you obtain information about the operating environment, test con- 
ditions in a command list, and take actions based on the results. 

See Appendix C, "Comparison of REXX and NetView Command List Language" on 
page 185 for a complete list of the rexx functions that are equivalent to NetView 
command list language control variables. This list includes both functions pro- 
vided by NetView and functions provided by rexx itself. See "Examples Comparing 
REXX and NetView Command List Language" on page 193 for examples of 
command lists written in the NetView command list language and the equivalent 
rexx command lists. 



Session Information 

APPLID() 

becomes the application program identifier for the task under which the 
command list is running, applidq is always the NetView domain id appended 
with a 3-character alphanumeric value assigned by NetView. For example, if 
your domain id is paris, applido might be parisool 

OPSYSTEM() 

becomes a character string that indicates the operating system for which 
NetView was compiled, opsystemo can contain the following character values: 

MVS/XA 
VM. 
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TASKO 

becomes the 3-character string ppt (primary poi task), ost (operator station 
task), or nnt (NetView-NetView task), depending on the task under which the 
command list is running, tasko allows the same command list to run under any 
of these tasks, because the command list can test for the task type and process 
accordingly. For example, there are some restrictions for command lists 
running under the ppt. See "Primary POI Task Restrictions" on page 17. 

VTAM() 

becomes a character string that indicates the level of the access method used. 
The variable is returned in one of two formats depending on whether the level 
of the access method includes a modification number. 

If the level of the access method does not include a modification number, the 
format of the variable is VTvr, where: 

VT - indicates the access method is VTAM 

v - indicates the version number of the access method 

r - indicates the release number of the access method. 

If the level of the access method does include a modification number, the 
format of the variable is Vvrm, where: 

V - indicates the access method is VTAM 

v - indicates the version number of the access method 

r - indicates the release number of the access method 

m - indicates the modification number of the access method. 

For example, for vtam Version 3 Release 2, the function would return a value of 
VT32. For vtam Version 3 Release 1 Modification 1, the function would return a 
value of V311. 

Note: The value of vtamq is null if vtam is not active. 



Terminal Information 



HCOPY() 

becomes the name of the hard-copy log printer started by the operator. If there 
is no hard-copy printer for this operator, hcopyo is null. 

LUO 

becomes the logical unit name for this operator terminal. 



Operator Information 



OPIDO 

becomes this operator's id. 



52 NetView Customization: Writing Command Lists 



REXX Command Lists 



Command List Information 



COMPNAMEO 

becomes the 16-byte name of the component running when the command list 
was initiated. For example, if command list help is initiated, compnameo 
defines the active component so that the correct help command list is initiated. 
compnameo can contain the following character values: 

DSINCCF DSINCCF 
DSINPDA 
DSINLDM 
DSIVIEW 1 
DSIVIEW 2 
DSIVIEW 3 
DSIVIEW 4 
DSIVIEW 5 
DSIVIEW 6 
DSIVIEW 7 
DSIVIEW 8 
DSIVIEW 9 
DSISTATMONRESUME 
DSILBROWSERESUME 
DSIVIEW APPL1 

PARMCNT() 

becomes the number of parameter variables that were entered when a 
command list was initiated. 



Message Processing Information 



MSGCNT() 

is the number of elements of text in the message string of the last message 
read by msgread. msgcnto is used with msgread and with the linkpd command. 

See "REXX MSGREAD Instruction" on page 40 for more information about 
using functions with msgread. 

See "LINKPD Results" on page 167 for more information about the linkpd 
command. 

MSGID() 

becomes the message identifier of the last message read by msgread. The 
message identifier is the first token of the message (up to 10 characters). If the 
first token is longer than 10 characters, msgido uses only the first 10 charac- 
ters. If a reply id is sent with the message, it is not used as the first token. For 
an mlwto message, msgido uses the first token of the first line of the first 
message, msgido is used in message automation, with msgread, and with the 
linkpd command. See Chapter 9, "Message Automation" on page 135 for 
more information about message automation. 

See "REXX MSGREAD Instruction" on page 40 for more information about 
using functions with msgread. 

MSGORIGN() 

is the domain where the last message read by msgread originated, msgorigno 
is used for message automation, with msgread, and with the linkpd command. 

See Chapter 9, "Message Automation" on page 135 for more information 
about message automation. 
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See "REXX MSGREAD Instruction" on page 40 for more information about 
using functions with msgread. 

See "LINKPD Results" on page 167 for more information about the linkpd 
command. 

MSGSTRO 

is the message text of the last message read by msgread. msgstro does not 
include the message identifier (the token used by the msgido function). For an 
mlwto message, msgstr becomes the message text of the first line of the 
message, msgstro is used with msgread and with the linkpd command. 

See "REXX MSGREAD Instruction" on page 40 for more information about 
using functions with msgread. 

See "LINKPD Results" on page 167 for more information about the linkpd 
command. 

MSGVAR(n) 

each msgvar(h) function is set to a token of the last message read by msgread. 
msgvar(1) is set to the token following the message identifier (the token used by 
the msgido function). msgvar(2) is set to the next token to the right of msgvar(1), 
and so on, up to a maximum of 31 variables. MSGVAR(n) is used for message 
automation, with msgread, and with the linkpd command. 

See Chapter 9, "Message Automation" on page 135 for more information 
about message automation. 

See "REXX MSGREAD Instruction" on page 40 for more information about 
using functions with msgread. 

See "LINKPD Results" on page 167 for more information about the linkpd 
command. 

The MSGVAR(n) functions can be given values when a command list is invoked in 
the same way the &1 - &31 NetView command list language parameter vari- 
ables can. See "Parameter Variables" on page 77 for more information on 
NetView command list language parameter variables. 

SESSID() 

is the id of the taf session that sent the message, sessido is used in message 
automation and with wait. See Chapter 9, "Message Automation" on page 135 
for more information about message automation. 

Note: If taf starts a session with a sessido equal to the domain id, sessido will 
not be set correctly, and message automation may not work. 

The remainder of this section contains descriptions of message information func- 
tions that are used only for message automation. More information about these 
functions can be found in MVS Systems Programming Library: Systems Macros 
and Facilities, Vol. 2. 

Some of these message information functions are filled with values only after 
NetView receives a message through the subsystem interface (ssi). The message 
information functions that have null values until NetView receives a message 
through the ssi are: 

• AREAIDQ 

• DESC() 

• JOBNAME() 

• JOBNUM() 
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MCSFLAG() 

MSGTYP() 

ROUTCDEO 

SMSGID() 

SYSCONID() 

SYSID(). 

AREAID() 

provides a one-letter (A-Z) identifier for the area on the console screen that 
displays the message. 

DESC() 

provides the system descriptor codes in a binary series of on (1) and off (0) 
characters, representing the descriptor code bits in order. 

HDRMTYPE() 

provides the 1-character NetView message type of the message. NetView 
message types are described in NetView Customization: Using Assembler. 

Note: hdrmtype is a NetView-supplied message function. 

JOBNAME() 

provides the 1- to 8-character mvs job name identifier. Because the jobname is 
the name of the job that originated the message, it may not always be the 
same as the name of the job to which the message is referring. For example, 
this can occur when mvs issues a message about the NetView job. Also, 
jobname can contain the name of an initiator (instead of the actual jobname) 
when a job is started or terminated. If the message is issued during startup or 
termination, extract the job name from the message text rather than using the 
jobname variable. 

JOBNUM() 

provides the 8-character mvs job number identifier. Depending on the mvs 
release, jobnumo can be a character string such as 'job 4', or simply a 
number such as ' 4'. 

Note: The appropriate number of blanks are imbedded within jobnum to 
ensure a total length of 8 characters. 

LINETYPEO 

provides the multi-line write-to-operator (mlwto) line type, as follows: 

C The line is a message control line. 

L The line is a message label line. 

D The line is a message data line. 

DE The line is the last message data line. 

E The line is the last message line and contains no data. 

blank The message is a single-line message. 

MCSFLAG() 

provides the system message flags in a binary series of on (1) and off (0) codes 
corresponding to the following meanings: 

first Send message conditionally to console sysconido 

second Send message unconditionally to console sysconido 

third resp 

fourth reply 

fifth brdcst 

sixth hrdcpy only 

seventh notime 

eighth nocpy. 
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MSGTYP() 

provides the system message type as three consecutive binary characters. An 
on character (1) in one of the positions corresponds to the following meanings: 

first sess 

second jobnames 
third status. 

REPLYID() 

provides a 3-character reply identifier for wtor command replies. See 
"WTOR" on page 140 for more information about the wtor command. 

ROUTCDE() 

provides the system routing codes in a binary series of on (1) and off (0) char- 
acters, representing the routing code bits in order. 

SMSGID() 

provides an 8-character value that identifies a particular instance of a 
message. This control variable is used by the dom command to identify action 
messages to be removed from the display. See "DOM" on page 141 for more 
information about dom. 

SYSCONID() 

provides the console number (in decimal) that is to receive the message. 

SYSID() 

provides an identifier for the mvs system that sent the message. 

WTOREPLY() 

is the reply sent by the operator in response to a wtor command. See 
"WTOR" on page 140 for more information about the wtor command. 



Domain Information 



NVCNT() 

becomes the number of NetView domains with which you can establish a 
cross-domain session. 

NVID(n) 

returns the NetView domain identifier of a domain with which you can establish 
a cross-domain session. If an invalid domain identifier is specified in n, an 
error is returned. To obtain the local domain identifier, use the applido func- 
tion, applido returns the local domain id appended with a 3-character alphanu- 
meric value assigned by NetView. 

NVSTAT(name) 

indicates whether you have an active session with a domain. If no name is 
specified or an invalid name is specified, an error is returned. 
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Chapter 5. Examples of REXX Command Lists for NetView 

This section contains examples of rexx command lists written for NetView. These 
examples show how the instructions and functions provided by NetView and the 
standard rexx instructions and functions can be used together in rexx command 
lists executing in a NetView environment. 
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TYPE Example 



/*********************************************** 



/* TYPE COMMAND LIST 






V 


~i 


/* ; _ 






V 


-i 


1 ,_ 


■1 


/* 






*/ 




/* FUNCTION: THIS COMMAND LIST DISPLAYS MEMBERS OF A DATA SET AT THE 


*/. 


.1 

'1 

■1 


/*■ (INVOKING) USER'S NETVIEW TERMINAL ONE LINE AT A TIME. 

/* 

/* INPUT PARMS: DATASETNAME » FULLY QUALIFIED DATA SET NAME 


*/ 

V 
V 




/* (INCLUDING MEMBER NAME) TO DISPLAY AT THE TERMINAL. 

/* 

/* OUTPUT: LINE = EACH LINE WITHIN THE MEMBER SPECIFIED BY THE USER. 


V 
V 
V 


.; 




/********************************************* 




ARG DATASETNAME 


/* 


PARSE CLIST INPUT 


*/■ 




IF DATASETNAME* 11 | PARMCNTQ > 1 THEN 


/* 


NO CLIST INPUT ? 


*/ 




DO 


/* 


NAME NOT SPECIFIED 


V 


1 


SAY • INCORRECT SYNTAX USED. ' 


/* 


ISSUE ERROR MSG 


*/ 




SAY 'CORRECT SYNTAX IS : ' 


/* 


ISSUE HELP MSG 


V 




SAY • TYPE DATASET. NAME (MEMBER) * 


/* 


ISSUE HELP MSG 


V 




RC=24 


/* 


SET RETURN CODE 


V 




END 


/* 


NAME NOT SPECIFIED 


V 




ELSE 


/* 


CORRECT NAME/SYNTAX 


*/ 




DO 


/* 


NAME WAS SPECIFIED 


*/ 




'TRAP AND SUPPRESS ONLY MESSAGES *' 


/* 


TRAP/SUPPRESS MSGS 


V 




'ALLOCATE DA ('DATASETNAME') SHR FREE' 


/* 


ALLOC/CONNECT FILE 


*/ 




'WAIT FOR MESSAGES' 


/* 


WAIT FOR MESSAGES 


*/ 




'MSGREAD' 


/* 


READ A MESSAGE IN 


7 




'TRAP NO MESSAGES* 


/* 


DISABLE TRAP MSGS 


V 




IF (MSGIDO-='CNM272D THEN 


/* 


IS MSG CNM272I ? 


V 




DO 


/* 


- CNM272I MSG 


V 




SAY MSGID() MSGSTRQ 


/* 


DISPLAY MESSAGE 


V 




END 


/* 


- CNM272I MSG 


*/■ 




ELSE 


/* 


MSG IS CNM272I 


V 




DO 


/* 


PROCESS CNM272I MSG 


V 




DDNAME = MSGVAR(l) 


/* 


SAVE DYNAMIC DDNAME 


V 




ADDRESS MVS 'EXECIG 1 DISKR 'DDNAME 


/* 


PUT 1ST LINE ON STACK 


V 




DO WHILE RC=0 


/* 


WHILE RC » 


V 




PULL RECORD 


/* 


PULL LINE FROM STACK 


V 




SAY SUBSTR( RECORD, 1,68) 


/* 


DISPLAY LINE TO USER 


V 






/* 


PUT NEXT LINE ON STACK*/ 




ADDRESS MVS 'EXECIO 1 DISKR 'DDNAME 






i 


END 


/* 


WHILE RC = 


V 






/* 


PUT OUT COMPLETE MSG 


V 


4 


'MESSAGE 3091 TYPE CLIST IS NOW FINISHED' 




i 


END 


/* 


PROCESS CNM272I MSG 


V 


END 


/* 


NAME WAS SPECIFIED 


V 




RETURN 


/* 


RETURN TO CALLER/EXIT 


V 


1 

J 



Figure 30. TYPE Example 
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TYPEIT Example 



/•••••A*********************************************************** 

V 
V 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/*■ 
/* 
/* 
/* 
/* 



TYPEIT COMMAND LIST 



FUNCTION: THIS COMMAND LIST DISPLAYS MEMBERS OF A DATA SET AT THE 
(INVOKING) USER'S NETVIEW TERMINAL ONE LINE AT A TIME. 

INPUT PARMS DATASETNAME = FULLY QUALIFIED DATA SET NAME 

(INCLUDING MEMBER NAME) TO DISPLAY AT THE TERMINAL. 

OUTPUT: LINE = EACH LINE WITHIN THE MEMBER SPECIFIED BY THE USER. 

CLIST FLOW : (AFTER CHECKING FOR PROPER INPUT PARMS) 

- ALLOCATE THE DATA SET & MEMBER SPECIFIED TO NETVIEW 

- READ ALL LINES OF MEMBER ONTO STACK WITH 'EXECIO * DISKR' 

- LOOP THROUGH STACK UNTIL NO MORE RECORDS EXIST <QUEUED()=0> 

- PUT. OUT THE FIRST 68 CHARACTERS OF THE LINE (FOR READABILITY) 

- PUT OUT CNM309I AT THE END 

- CLOSE THE FILE WITH 'EXECIO DISKR ... ( FINIS' WHETHER AN 
ERROR OCCURS OR NOT. 



SIGNAL ON HALT 
ARG DATASETNAME 

IF DATASETNAME^" | PARMCNTQ > 1 THEN 
DO 
SAY 'INCORRECT SYNTAX USED.' 
SAY 'CORRECT SYNTAX IS : ' 
SAY ' TYPE DATASET. NAME (MEMBER) ' 
RC=24 
END 
f ELSE 
DO 

'TRAP AND DISPLAY ONLY MESSAGES CNM272I' 
'ALLOCATE DA ('DATASETNAME') SHR FREE' 
'WAIT 5 SECONDS FOR MESSAGES' 
•MSGREAD' 
1 'TRAP NO MESSAGES' 

IF (MSGIDO— 'CNM272I') THEN 
DO 

SAY MSGIDQ MSGSTRQ 
END 
ELSE 
* DO 

ODNAME = WORD (MSGSTR ( ) , 1 ) 
' ADDRESS MVS 'EXECIO * DISKR 'DDNAME 
DO UNTIL QUEUEDQ = 

Figure 31 (Part 1 of 2). TYPEIT Example 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/*■ 
7* 
/* 
/* 
/* 



PROCESS TERMINATION 
PARSE CLIST INPUT 
NO CLIST INPUT ? 
NAME NOT SPECIFIED 
ISSUE ERROR MSG 
ISSUE HELP MSG 
ISSUE HELP MSG 
SET RETURN CODE 
NAME NOT SPECIFIED 
CORRECT NAME/SYNTAX 
NAME WAS SPECIFIED 
TRAP/DISPLAY CNM272I 
ALLOC/CONNECT FILE 
WAIT FOR MESSAGES 
READ A MESSAGE IN 
DISABLE TRAP MSGS 
IS MSG CNM272I ? 

- CNM272I MSG 
DISPLAY MESSAGE 

- CNM272I MSG 
MSG IS CNM272I 
PROCESS CNM272I MSG 
SAVE DYNAMIC DDNAME 
READ DATA ONTO STACK 
WHILE RC * 



V 
V 
*/ 
V 

*/ 
*/ 

7 
V 
*/ 
V 
V 
V 
V 
V 
V 
V 
V 

*/ 

V 
V 

*/ 
*/ 

V 
V 
V 
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PULL RECORD /* PULL LINE FROM STACK */ 

SAY SUBSTR(REC0RD f l,68> /* DISPLAY LINE TO USER */ 

/* PUT NEXT LINE ON STACK*/ 
END ■■./* WHILE RC = 

/* PUT OUT COMPLETE MSG 
'MESSAGE 3091 TYPEIT CLIST IS NOW FINISHED* 

/* PROCESS CNM272I MSG 
END /* NAME WAS SPECIFIED 



7 
7 



7 

7 



/* CLOSE THE FILE WHETHER OR NOT AN ERROR HAS OCCURRED */ 

HALT: /* SIGNAL ON HALT LABEL */ 

ADDRESS MVS 'EXECIO DISKR 'DDNAME '( FINIS'/* CLOSE THE FILE */ 

RETURN /* RETURN TO CALLER/EXIT */ 



Figure 31 (Part 2 of 2). TYPEIT Example 



PRINT Example 



/•♦••♦♦••A************************************* 

/*' 
/* 
/* 

/* 
/* 
/* 

INPUT PARMS: DATASETNAME = FULLY QUALIFIED DATA SET NAME 

(INCLUDING MEMBER NAME) TO DISPLAY AT THE TERMINAL. 



PRINT COMMAND LIST 



FUNCTION: THIS COMMAND LIST PRINTS MEMBERS OF A DATA SET TO A 
SYSTEM PRINT FILE. 



/* 
/* 

/* 

/* OUTPUT: A SYSTEM PRINT FILE 



7 

7 

V 

V 

V 

7 

*/■ 

*/ 

V 

V 



ARG DATASETNAME 

IF DATASETNAME'" | PARMCNTQ > 1 THEN 

• •■Da.- ■ : ■ 

SAY 'INCORRECT SYNTAX USED.' 
SAY 'CORRECT SYNTAX IS : ' 
SAY 1 PRINT DATASET. NAME (MEMBER) 
RC=24 
END 
ELSE 
DO 

'TRAP DISPLAY ONLY MESSAGES ** 
'ALLOCATE SYSOUT(A) FREE RECFM(FB) ' ,.. 

'LRECL(8Q) BLKSIZECAGGO)' 
'WAIT FOR MESSAGES' 
'MSGREAD* 

Figure 32 (Part 1 of 2). PRINT Example 



/* 
/*■■ 

7* 
/* 
7* 
/* 
/* 
/* 
7* 
/* 
/* 
/* 
/* 
I* 
/* 



PARSE CLIST INPUT 
NO CLIST INPUT ? 
NAME NOT SPECIFIED 
ISSUE ERROR MSG 
ISSUE HELP MSG 
ISSUE HELP MSG 
SET RETURN CODE 
NAME NOT SPECIFIED 
CORRECT NAME/SYNTAX 
NAME WAS SPECIFIED 
TRAP/SUPPRESS MSGS 
ALLOC/CONNECT SYSTEM 
... PRINTER FOR USAGE 
WAIT FOR RESULTS 
READ A MESSAGE IN 



V 

*/ 

V 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
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IF (MSGID()-.»'CNM272r) THEN 
DO 

SAY MSGIDQ MSGSTRQ 
END 
ELSE 
DO 
ODNAMEO = MSGVAR(l) 
'TRAP AND DISPLAY ONLY MESSAGES 



/* 
/* 
/* 
/* 
/* 
/* 

■/* 

/* 



•ALLOCATE DACDATASETNAME') SHR FREE'/* 

•WAIT FOR MESSAGES' 

'MSGREAD' 

'TRAP NO MESSAGES' 

IF (MSGIDQ— 'CNM272I') THEN 

DO 
SAY MS6ID() MSGSTRO 

END 
ELSE 



DDNAMEI = MSGVAR(l) 
ADDRESS MVS 'EXECIO 1 DISKR 
DO WHILE RC=0 

ADDRESS MVS 

ADDRESS MVS 
END 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 

/* 

DDNAMEI 



IS MSG CNM272I ? 

- CNM272I MSG 
DISPLAY MESSAGE 

- CNM272I MSG 
MSG IS CNM272I 
PROCESS 1ST CNM272I 
SAVE OUTPUT DDNAME 
TRAP/SUPPRESS MSGS 
ALLOC/CONNECT FILE 

./* WAIT FOR MESSAGES 
READ A MESSAGE IN 
DISABLE TRAP MSGS 
IS MSG CNM272I ? 

- CNM272I MSG 
DISPLAY MESSAGE 
-* CNM272I MSG 
MSG IS CNM272I 
PROCESS 2ND CNM272I 
SAVE INPUT DDNAME 

/* READ 1ST LINE 



•EXECIO 
'EXECIO 



END 



END 



RETURN 



/* WHILE RC * 
DISKW 'DDNAMEO /* WRITE LINE OUT 
DISKR 'DDNAMEI /* READ NEXT LINE 
/* WHILE RC = Q 
I* PUT OUT COMPLETE MSG 
'MESSAGE 309I TYPE CLIST IS NOW FINISHED' 
END /* PROCESS 2ND CNM272I 

/* PROCESS 1ST CNM272I 
/* NAME WAS SPECIFIED 



V 
*/ 
V 
V 
*/ 
*/ 
V 
*/ 
V 
*/ 

V 
V 

V 
V 
V 

.*/ 
*/ 
*/ 
*/ 
*/ 

V 

*/ 

V 
V 
V 

■V 

'*/ 



7 



/* RETURN TO CALLER/EXIT */ 



Figure 32 (Part 2 of 2). PRINT Example 
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/* 7 

/*■ THE FOLLOWING REXX COMMAND LIST IS A FAIRLY SIMPLE EXAMPLE */ 

/* OF HOW SOME OF THE BASIC REXX FUNCTIONS AND NETVIEW-SPECIFIC */ 

/* FUNCTIONS CAN BE USED IN A COMMAND LIST. IT ILLUSTRATES THE USAGE*/ 

/* OF SUCH THINGS AS THE REXX 'PARSE' INSTRUCTION, AND THE NETVIEW */ 

/* SUPPLIED 'MSGTRAP', 'WAIT 1 , 'MSGREAD', AND 'GLOBALV COMMMANDS. */ 

/* 7 

'/* 7 

/* COMMAND LIST NAME: CHKOPNUM */' 

/* 7 

/* THIS COMMAND LIST CAN BE USED PERIODICALLY TO CHECK THE */ 

7* NUMBER OF OPERATORS CURRENTLY LOGGED ON, AND WILL KEEP THE */ 

/* INFORMATION IN COMMON GLOBAL VARIABLES. THE INFORMATION */ 

/* COLLECTED CAN LATER BE RETRIEVED BY USING THE 'DISPLAY' */ 

/* OPTION. 7 

/* 7 

/* INPUT: 7 

/* " - WILL CHECK THE NUMBER OF OPERATORS LOGGED ON */ 

/* AND UPDATE APPROPRIATE COMMON GLOBAL VARIABLES */ 

/* 'DISPLAY 1 - WILL ANALYZE THE VALUE IN THE COMMON GLOBAL */ 

/* VARIABLES AND DISPLAY THE RESULTS */ 

I* ANY OTHER 7 

/* INPUT - WILL DEFAULT TO " */ 

/* 7 

/* USAGE EXAMPLE: 7 

/* 1. EXECUTE THE FOLLOWING TO CAUSE THE NUMBER OF OPERATORS */ 

/* TO BE CHECKED EVERY HOUR (COULD BE ANY TIME PERIOD): */ 

/* -> 'EVERY 01:00, PPT,CHKOPNUM' */ 

/* 2. AT ANY TIME, EXECUTE THE FOLLOWING COMMAND TO DISPLAY THE */ 

./* RESULTS OF THE PREVIOUS EXECUTIONS: */ 

■ I* -> 'CHKOPNUM DISPLAY */ 

/* RESULTS WILL BE DISPLAYED ON YOUR TERMINAL */ 

/* 7 

/* CHANGE CODE DATE DESCRIPTION 7 

/* — — — 7 

/* 7 

/•it*********************************************************** 

PARSE ARG OPTION /* GET INPUT, IF ANY *f 

I* GET VALUES FOR COMMON GLOBAL VARIABLES USED BY THIS EXEC */ 
'GLOBALV GETC CHKOPTIMES, CHKOPNUM, CHKOPMAX' 

IF OPTION = 'DISPLAY' THEN DO; /* WAS 'DISPLAY' REQSTD? */ 

IF CHKOPTIMES = " THEN /* ANYTHING TO DISPLAY? */ 
SAY 'NUMBER OF OPERATORS HAS NEVER BEEN CHECKED '/* NO, GIVE ERROR7 



Figure 33 (Part 1 of 2). CHKOPNUM Example 



•3 
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ELSE DO; /* YES, DISPLAY RESULTS */ 

SAY 'NUMBER OF OPERATORS HAS BEEN CHECKED ' CHKOPTIMES * TIMES' 

SAY 'AVERAGE NUMBER OF OPERATORS LOGGED ON IS: 'CHKOPNUM/CHKOPTIMES 

SAY 'MAXIMUM NUMBER OF OPERATORS LOGGED ON IS: 'CHKOPMAX 
END; /* END DISPLAY RESULTS */ 

EXIT 0; /* EXIT FROM COMMAND LIST*/ 

END; /* END DISPLAY OPTION */ 



CUROPNUM = 

'TRAP AND SUPPRESS MESSAGES OPERATOR:, END' 

•LIST STATUSES' 

DO UNTIL MSGID()='END' 

'WAIT FOR MESSAGES' 

'MSGREAD* 

IF MSGIDO = 'OPERATOR:' THEN 
CUROPNUM = CUROPNUM +1 

ELSE NOP 
END 

IF CHKOPTIMES = ' ' THEN CHKOPTIMES = 1 
ELSE CHKOPTIMES = CHKOPTIMES + 1 
IF CHKOPNUM = ' ' THEN CHKOPNUM = CUROPNUM 
ELSE CHKOPNUM = CHKOPNUM + CUROPNUM 
IF CHKOPMAX = ' ' THEN CHKOPMAX = CUROPNUM 
ELSE IF CHKOPMAX < CUROPNUM THEN CHKOPMAX = 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 



TRAP LIST RESPONSE */ 
ISSUE LIST COMMAND */ 
LOOP TILL END OF MSGS */ 
WAIT FOR RESPONSE */ 
YES, READ IN MESSAGE */ 
IS IT AN OPERATOR LINE*/ 
YES, INCREMENT # OPS */ 
NO, MUST BE 'END' MSG */ 



/* INCREMENT # TIMES CHKD*/ 

/* INCREMENT #OPS ON SYS */ 

/* INCREMENT MAX IF NEED */ 
CUROPNUM 



/* PUT NEW VALUE BACK INTO THE COMMON GLOBAL VARIABLE DICTIONARY */ 
'GLOBALV PUTC CHKOPTIMES, CHKOPNUM, CHKOPMAX* 



EXIT 0; 



/* END OF COMMAND LIST */ 



Figure 33 (Part 2 of 2). CHKOPNUM Example 



Chapter 5. Examples of REXX Command Lists for NetView 63 



REXX Command Lists 



CHKRSTAT Example 



./* V 

/* THE FOLLOWING REXX COMMAND LIST IS MORE COMPLEX THAN CHKOPNUM. */ 

/* IT ILLUSTRATES USAGE OF SUCH THINGS AS THE REXX 'INTERPRET' */ 

/* INSTRUCTION, AND THE NETVIEW 'WAIT* (FOR MESSAGES AND TIME), */ 

/* AND THE 'GETMLINE' /* COMMAND (FOR MULTI-LINE MESSAGES) */ 

/* V 

/************************************•*********** 

/* */' 

/* COMMAND LIST NAME: CHKRSTAT */ 

/* V 

/* THIS COMMAND LIST CHECKS WHETHER A SPECIFIED RESOURCE */ 

/* IS ACTIVE, AND INCREMENTS A COMMON GLOBAL VARIABLE THAT */ 

/* REFLECTS THE NUMBER OF TIMES IT WAS IN THAT STATE. THIS */ 

/* COMMAND LIST SHOULD BE SCHEDULED TO RUN UNDER AN AUTOTASK */ 

/* AT REGULAR. INTERVALS. */ 

/* V 

/* INPUT PARAMETERS: */ 

/* RESNAME - NAME OF RESOURCE TO CHECK STATUS OF */. 

/* 7 

/* CHANGE CODE DATE DESCRIPTION */ 

/* — - ----- " */■ 

/* */ 

PARSE UPPER ARG RESNAME /* GET INPUT, IF ANY */ 

/* IF NO RESROUCE NAME GIVEN, DISPLAY ERROR MESSAGE AND EXIT */ 
IF RESNAME = " THEN DO; 

SAY 'RESOURCE NAME MUST BE PROVIDED* 

EXIT 99 

END 

/* SET UP TRAP FOR POSSIBLE RESPONSES TO 'D NET,ID=« COMMAND, ISSUE */ 

/* COMMAND, AND WAIT FOR MESSAGE TO ARRIVE */ 

'TRAP AND SUPPRESS MESSAGES IST097I IST075I IST453I' 

'D NET, ID=' RESNAME 

•WAIT 60 SECONDS FOR MESSAGES' 

/* IF MESSAGE DID NOT ARRIVE, THEN GIVE ERROR MESSAGE AND EXIT */ 
IF EVENTQ "« 'M' THEN DO 

SAY ' NO RESPONSE FROM VTAM - RESOURCE COUNT NOT UPDATED ' 

EXIT 99 

END 

/* READ MESSAGE. IF IT IS IST097I, ISSUE WAIT AGAIN, AND THE NEXT */ 

/* MESSAGE READ SHOULD BE IST075I, WHICH HAS THE STATUS INFO */' 

'MSGREAD' 

IF MSGIDQ = 'IST097I' THEN DO; 

'WAIT CONTINUE' 

'MSGREAD' 

Figure 34 (Part 1 of 2). CHKRSTAT Example 
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/* IF THE MESSAGE IS NOT IST075I, 00 NOTHING, AND THE STATUS WILL */ 
/* DEFAULT TO INACTIVE. IF IT IS IST075I, GET THE 2ND LINE OF THE */ 
/* MULTI-LINE MESSAGE AND GET THE CURRENT STATE FROM THAT LINE */ 
IF MSGIDQ = »IST075r THEN DO 
'GETMLINE STATLINE ' 2 

/* IF STRING CONTAINS IST486I THEN PARSE OUT RESOURCE STATUS */ 
IF INDEX(STATLINE,'IST486I') >0 THEN 

PARSE VALUE STATLINE WITH MSGTXT1 'CURRENT STATE »* RESSTATE . 
END 
END 

/* IF THE CURRENT STATE IS ACTIVE OR ACTIVE W/SESSION, THEN GET */ 
/* INCREMENT AND UPDATE THE COMMON GLOBAL VARIABLE WITH THE NAME */ 
/* 'RESOURCE NAME' CONCATENATED WITH '@A'. NOTE THAT SINCE THE */ 
/* GLOBALV COMMAND REQUIRES THE VARIABLE NAME, A VARIABLE HAS */ 
/* TO BE SET TO THE VARIABLE NAME, SINCE IT IS DYNAMICALLY */ 

/* CONSTRUCTED. THE REXX INTERPRET INSTRUCTION MUST ALSO BE USED */ 
/* TO PERFORM OPERATIONS ON THE DYNAMICALLY CONSTRUCTED VARIABLE */ 
■IF RESSTATE * 'ACTIV | RESSTATE - 'ACT/S' THEN DO 

VARNAME = RESNAMEH'GA' 

'GLOBALV GETC 'VARNAME 

INTERPRET 'ACT# =' VARNAME' 

IF DATATYPE (ACT#) -« 'NUM' THEN ACT# =1 /* IF NON-NUMERIC */ 

ELSE ACT# - ACT# +1 

INTERPRET VARNAME '=ACT#' 

'GLOBALV PUTC 'VARNAME 
END 

/* IF THE CURRENT STATE IS NOT ACTIVE OR ACTIVE W/SESSION, THEN GET */ 
/* INCREMENT AND UPDATE THE COMMON GLOBAL VARIABLE WITH THE NAME */ 
/* 'RESOURCE NAME' CONCATENATED WITH »eNA\ NOTE THAT SINCE THE */ 
./* GLOBALV COMMAND REQUIRES THE VARIABLE NAME, A VARIABLE HAS */ 
/* TO BE SET TO THE VARIABLE NAME, SINCE IT IS DYNAMICALLY */ 

/* CONSTRUCTED. THE REXX INTERPRET INSTRUCTION MUST ALSO BE USED */ 
/* TO PEFFORM OPERATIONS ON THE DYNAMICALLY CONSTRUCTED VARIABLE */ 
ELSE DO 

VARNAME = RESNAME||*0NA' 

•GLOBALV GETC 'VARNAME 

INTERPRET 'NACT# =' VARNAME 

IF DATATYPE (NACT#) — 'NUM' THEN NACT# =1 /* IF NON-NUMERIC */ 
ELSE NACT# = NACT# +1 

INTERPRET VARNAME ' =NACT# ' 

•GLOBALV PUTC 'VARNAME 
END 
exit 0: 



Figure 34 (Part 2 of 2). CHKRSTAT Example 
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DSPRSTAT Example 



/•••••♦A******************************************************* 



7* 
7* 
7* 
/* 
/* 
/*■ 
/* 
/* 
/* 
/* 



THE FOLLOWING REXX COMMAND LIST GOES ALONG WITH THE PREVIOUS 
EXAMPLE (CHKRSTAT), AND SHOWS MANY OF THE SAME TYPE OF FUNCTIONS 
AS THE PREVIOUS EXAMPLE. 



THIS COMMAND LIST COULD BE USED BY ANY OST OPERATOR TO DISPLAY 
THE RESULTS OF SEVERAL EXECUTIONS OF THE CHKRSTAT COMMAND LIST 
FOR A SPECIFIC RESOURCE. IT COULD BE USED AS AN AID IN 
DETERMINING HOW OFTEN A RESOURCE IS ACTIVE, BASED ON THE INTERVALS*/ 
IN WHICH IT WAS CHECKED BY THE CHKRSTAT COMMAND LIST */ 



V 

V 
*/ 
*/ 
*/ 

V 
V 

*/ 



/* V 

/♦•A************************************************* 

V 

COMMAND LIST NAME: DSPRSTAT */ 

V 
THIS COMMAND LIST CAN BE USED TO DISPLAY HOW OFTEN A RESOURCE */ 

WAS ACTIVE VS. NOT ACTIVE, AS RECORDED BY THE CHKRSTAT COMMAND */ 

LIST 



/* 

/* 

/* 

7* 

/* 

/* 

/* 

/* 

/* 

/* 

/* 

/* 
/A****************************************************** 

PARSE UPPER ARG RESNAME /* GET INPUT, IF ANY */ 



INPUT PARAMETERS: NONE 

CHANGE CODE DATE DESCRIPTION 



V 
V 
V 
V 
V 

*/ 

V 



/* IF NO RESOURCE NAME GIVEN, DISPLAY ERROR MESSAGE AND EXIT 
IF RESNAME = "THEN DO; 

SAY 'RESOURCE NAME MUST BE PROVIDED' 

EXIT 99 

END 



7 



VARNAMEA = RESNAME||'@A' 
VARNAMENA = RESNAME|| ' @NA ' 
'GLOBALV GETC 'VARNAMEA' 
•GLOBALV GETC 'VARNAMENA 
INTERPRET ' RACT= ' VARNAMEA 
INTERPRET 'RINACT = 'VARNAMENA 



/* 
/* 
■/* 
/* 
/* 
/* 



SET THE VAR NAME ACT */ 
SET THE VAR NAME NACT */ 
GET THE ACTIVE INFO */ 
GET THE INACTIVE INFO */ 
PUT ACTIVE # IN VAR */ 
PUT INACTIVE # IN VAR */ 



/* DISPLAY THE STATISTICS FOF THE RESOURCE SPECIFIED 
IF RACT = " & RINACT = " THEN 
SAY 'NO STATISTICS HAVE BEEN COLLECTED FOR RESOURCE: 



RESNAME 



7 



:/. 



/* DISPLAY THE STATISTICS FOR THE RESOURCE SPECIFIED 

ELSE DO 

IF DATATYPE (RACT) — 'NUM 1 THEN RACT = '/* IF NOT NUMERIC */ 

IF DATATYPE (RINACT) . -~ 'NUM* THEN RINACT = /* IF NOT NUMERIC*/ 

Figure 35 (Part 1 of 2). DSPRSTAT Example 
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i SAY 'RESOURCE 'RESNAME' STATISTICS:* 

I SAY ' NUMBER OF TIMES RESOURCE WAS ACTIVE : «RACT 

I SAY • NUMBER OF TIMES RESOURCE WAS INACTIVE: 'RINACT 

| PERCENTACT - RACT/CRACT+RINACT)*^!^' /* DETERMINE PERCENT */■ 

I SAY • PERCENTAGE OF TIMES RESOURCE WAS ACTIVE: 'PERCENTACT 

f END 

|- EXIT 0; 

Figure 35 (Part 2 of 2). DSPRSTAT Example 
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Chapter 6. Simple NetView Command List Language 
Command Lists 

In this chapter, you will learn the basics of writing command lists for the NetView 
program using the NetView command list language. This chapter also describes 
how variables, assignment statements, and built-in functions fit together and how 
to combine them in command lists. 

In simple command lists, each statement is interpreted in the order it appears. 
One or more segments of your application processing are performed in sequence 
as coded. Simple command lists do not give you the flexibility to skip around some 
segments, to perform alternate segments, or to repeat processes. These features 
are included in the NetView command list language, and you will learn about them 
in Chapter 7, "NetView Command List Language Branching" on page 107. 

A comprehensive sample command list, with examples of each type of statement in 
this chapter, appears in "Sample Command List— Chapter Review" on page 105. 
Also, see "Examples Comparing REXX and NetView Command List Language" on 
page 193 for samples of command lists written in the NetView command list lan- 
guage and the equivalent rexx command lists. 

What the NetView Command List Language Includes 

The NetView Command list language is made up of statements, each having a sep- 
arate function. NetView uses the following six types of command list statements: 

• Command 

• Comment 

• Control 

• Assignment 

• Label 

• Null. 

You can use the following features of the command list language within command 
list statements: 

• Parameter variables 

• Control variables 

• User variables 

• Global variables 

• Built-in functions. 

All of these, except global variables, are discussed in detail in later sections of this 
chapter. Global variables and descriptions of passing parameter values are 
described in Chapter 8, "NetView Command List Language Global Variables." 
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The NetView command list language also gives you the capability to write applica- 
tion code to perform repetitive or alternate processing (if-then or loop structures). 
These features are implemented with the following control statements: 

• &IF 

• &GOTO 

• &EXIT 

• &WAIT. 

These control statements are discussed in Chapter 7, "NetView Command List 
Language Branching." 

Note: Command lists can interrupt the processing of other command lists. This is 
done using the cmdmdl statement in the dsicmd. For more information, see Netview 
Administration Reference. 



Coding Conventions for NetView Command List Language 
Statements 

Like any other language, the NetView command list language requires that you 
follow syntax rules. The following coding conventions for NetView are divided into 
sections describing the conventions for general coding, continuation characters, 
suppression characters, and double-byte character sets. 

Note: The syntax diagrams used in this book are formatted according to the 
coding conventions described under "Coding Conventions Used in This Book" on 
page xiv. 

General Coding Conventions 

Use the following coding conventions when writing command lists in the NetView 
command list language: 

• Optionally, code a clist statement as the first line of your command list. Code 
clist statements as follows: 

- Optionally, code a label. The label must begin in column one. 

- Code the characters clist beginning in column two or later, clist must be 
preceded by at least one blank. 

Note: On vm systems, if the command list is not defined on a cmdmdl defi- 
nition statement, you must start the command list with a clist statement. It 
is not optional. 

• Leave column 72 blank for all statements. 

• Do not use columns 73-80. They are reserved for optional sequence numbers. 

• Code at least one blank after a label (if there is one) or before a keyword. 

• Code at least one blank between a control statement and the first operand. 

• Separate operands with one or more blanks, or a single comma with no blanks. 

• Code any number of leading or trailing blanks on your statements. 



• Use lowercase letters only as comments or part of a message sent to the oper- 
ator. In all other cases, use uppercase for alphabetical characters A-Z. 
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Code statements so that their maximum length is 240 characters after variable 
substitution. To familiarize yourself with how variable substitution works, see 
"Variable Substitution Order" on page 76. 

Code comment lines with an asterisk (*) in the first column followed by the 
comment. Comment records cannot appear on the first line of a command list. 

Code the command list so that it ends by processing the last command list 
statement, or by reaching an &exit statement. An operator entering reset also 
ends the command list. 

Conventions for Continuation Statements 

Use a plus sign (+) or a hyphen (-) as a continuation character to continue a state- 
ment that is too long to fit on one line. Code the continuation character as the last 
non-blank character before column 72 on the line to be continued. 

Note: Do not code a comment between the beginning and end of a continued 
statement. 



• 



• 



• 



The plus sign causes the text of the continuation line to begin where the plus 
sign was placed without any of the blanks leading up to the first non-blank 
character on the continued line. 

The plus sign causes these lines: 

&WRITE THIS STATEMENT IS CODED + 

AS + 
THREE LINES 

to become this single statement: 

THIS STATEMENT IS CODED AS THREE LINES 

The hyphen causes NetView to keep all the blanks at the end of the line with 
the hyphen (up to but not including column 72) and then fill the line to its end 
with characters from the beginning of the continuation line. The hyphen itself 
is replaced by a blank. When filling a line with characters from the beginning 
of the continuation line, NetView presentation services does not split a word 
across lines of an output screen. The last character used for filling in from the 
continuation line must be a blank or the last character on the line. 

For example, if you coded the following &write statement to be displayed on an 
80-character-wide terminal: 

&WRITE STATEMENT CONTINUED WITH THE HYPHEN TO KEEP - 
BLANKS 

all the blanks from the p in keep to the b in blanks would be kept. The first line 
would write 64 characters to the output screen (41 characters of text plus 23 
blanks from the end of the text to column 72). The output screen has 68 
columns to be used for display (80 minus the 12-character prefix), so the 
hyphen would cause the first four characters of the second line to be placed at 
the end of the first line. In the example, this would be two blanks and the 
letters bl. However, since NetView presentation services will not split a word 
across lines of the output screen, the example would be displayed as: 

STATEMENT CONTINUED WITH THE HYPHEN TO KEEP 
BLANKS 
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Conventions for Double-Byte Character Set Text 

A double-byte character set (dbcs) is a character set in which each symbol is 
represented by a two-byte code rather than one-byte codes. For example, Kanji is 
a language used in Japan that is too rich in symbols to display all the characters 
using one-byte codes. Therefore, a double-byte character set is used. Double-byte 
character set support is available for mvs/xa only. 

In the following, dbcs refers to double-byte character set characters. The term 
"Latin characters" refers to the English character set, a-z and A-Z. 

• Use a Latin character set to code NetView commands and command lists used 
as commands. 

• dbcs data input is not supported. 

• Enclose all dbcs strings within shift-out (X'OE*) and shift-in (X'OF') codes. Be 
sure there are an even number of characters in each dbcs string (if you are 
using an editor and terminal that supports double-byte characters this is done 
automatically). 

• Label names and variable values can be coded in dbcs characters. Restrict 
them to a length of 11 bytes. 

• When dbcs labels and variables are displayed on a dbcs terminal, the shift-out 
and shift-in codes appear as blanks. 

• dbcs text can be split across multiple lines, using an ebcdic plus sign (+) or 
hyphen (-) as a continuation character. 

• When writing dbcs text in a &begwrite, the sub option is required. 



• 



Comments can contain dbcs strings enclosed by shift-out (X'OE') and shift-in 
(X'OF") codes. 



• &write, &concat, and &substr are enabled for double-byte character sets. 

Conventions for Suppression Characters 

You can define a suppression character with the suppchar operand of the nccfid 
definition statement and use it to prevent a command list command or statement 
from appearing on the operator's screen. See NetView Administration Reference 
for more information about the nccfid definition statement. 

The following rules apply when coding suppression characters: 

• Code the suppression character in column 1 of the statement. 

• Only the first line of a continued statement can be suppressed when the 
command list is listed using the listclist= command. 

• When you browse a file, you can see every line, even suppressed lines. 

In Figure 36 on page 75, the question mark (?) has been defined as a suppression 
character. The first and last lines of the command list in the example will be sup- 
pressed. 
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f ■-■■ -• -•"■■• " •■' • ' ' ' 

1 7* COMMAND LIST UPDATEO 2/5/87 BY OPERATOR IRENE 

5START D0MAIN=&1 

t&WRITE ENTER 60 WHEN MESSAGE DSI809I ARRIVES FROM &1 

■ &PAUSE 

|?ROUTE &1,0PER1, 123456 

Figure 36. Suppression Characters 

When issuing a command that returns its status in the return code, you can sup- 
press synchronous output from the command by coding the suppression character 
twice. For example, if you coded: 

??SET PF24 IMMED RETRIEVE 

in a command list, no synchronous output from the command list is displayed to 
the operator. 

Use the double suppression character to enhance performance on commands that 
produce line mode messages synchronously and when sufficient status is provided 
by the return code. Using the double suppression character does not affect output 
that is scheduled by a command (for example, d net.appls) nor does it reliably 
reduce output from a long running command (for example, nldm). 



Labels identify command list statements for control of flow, or internal documenta- 
tion, or to indicate the target statement for a transfer of control. You will learn how 
to use transfer of control in Chapter 7, "NetView Command List Language 
Branching" on page 107. 

Labels can be coded on any command list statement, except a comment statement. 
This means you can code labels on commands, control statements, assignment 
statements, and null statements. If NetView cannot find the label, processing 
stops, and NetView issues an error message. 

Code the label as the first non-blank word in the command list line. A label con- 
sists of an ebcdic hyphen (-) followed by one to eleven characters (A-Z, 0-9, #, @, 
$). Start the command list statement after the label, leaving at least one blank 
between the label and a keyword. Labels can be used on null lines, so you do not 
have to code a command list statement after a label. 

You can also code other labels. All labels must be unique within a command list. 
If you have two identical labels in one command list, NetView ends the command 
list. You can also code labels as internal comments to show where different parts 
of your command list start. For example, you can use labels to highlight certain 
processing routines. 
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Figure 37 shows examples of labeled command list statements. 



•MYLABEL VARY NET,INACT,ID=LU1234 
-$PR0C2 &LEK = &LENGTH &1 
-SETUP &USER - 55 
-ALLALQNE 



Figure 37. Labels in Command List Statements 

Note: Labels are used with &begwrite to show where a message stops. Variables 
are not allowed in labels, but you can code a variable as the label name with the 
&BEGWRUE, &GOTO, or &wait statements. These statements for transfer of control are 
described in Chapter 7, "NetView Command List Language Branching" on 
page 107. 

Variables 

Variables let you accept from an operator, or define for yourself, different values 
for the statements within a command list. With variables, you can write a 
command list that operates correctly in many different situations. There are four 
types of variables: 

• Parameter 

• Control 

• User 

• Global. 

In this section you will learn how to use parameter, control, and user variables. 
This section also describes how to use the NetView parsel2R command to parse 
variables in a command list. See Chapter 8, "NetView Command List Language 
Global Variables" on page 123 for a description of global variables. 

Variable Substitution Order 

Variable substitution is performed when NetView scans each statement from right 
to left and substitutes values for each variable. This is done as follows: 

1. Each element is scanned from right to left for an ampersand (&). 

Note: The value of X'50' (ampersand in the English character set) is ignored 
within double-byte character sets. 

• If found, the ampersand and the rest of the element to the right are substi- 
tuted with the value of that variable. 

• If no value exists, the variable becomes null. 

• If the first character to the right of the ampersand is a number, the variable 
is assumed to be a parameter variable. NetView then scans to the right 
and takes any following numbers as part of the parameter variable. When 
NetView comes to a blank or a letter, the search stops. If a special char- 
acter (non-alphanumeric) is found, it delimits the variable name. 

For example, &21A is taken as &21 and is replaced by the value of &21. 
Therefore, &21A becomes valueA. For another example, if an element 
contains &a=&xyz, NetView first substitutes the value of &xyz, then NetView 
replaces &a with the value it has just substituted for &xyz. 
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2. The scan resumes at the next character to the left, and the search for an 
ampersand continues. If found, the ampersand and the entire syntactical 
element to the right, including the previous substitution, are taken as the name 
of a variable and are replaced by its value. Note that the value substituted is 
not scanned for an ampersand. 

If the element is the target of an assignment statement, the scan stops on the 
second character to preserve the variable name that will be assigned a value. 
For example, the statements in Figure 38 set the value of user variable &A1 to 
2. 

t&A&B *-$|S|£S^^ ■ "'.'■ ■ 

Figure 38. Variable Substitution Example 

Variable substitution is not done on the following features of the language: 

• The &pause statement 

The variables are assigned values when you enter a go command. For 
more information, see "&PAUSE Control Statement" on page 97. 

• The &then clause on an &if statement 

If the &if clause is true, the &then clause is made into a statement and 
processed as if it had been coded separately. For more information, 
see "&IF Control Statement" on page 107. 

• Any statements in an &begwrite nosub series of messages 

For more information, see "&BEGWRITE Control Statement" on 
page 95. 

• Control keywords 

For more information, see "&CONTROL Control Statement" on 
page 92. 

• Built-in functions 

For more information, see "Built-in Functions" on page 99. 

Parameter Variables 

A parameter variable is a positional variable that is defined at the time a command 
list is run. You specify parameter variables by entering them as operands fol- 
lowing the name of the command list that you are running. Parameter variables 
have the following characteristics: 

• Identified within the command list by a numbered position, for example, &1 

• Entered following the command list name at run time 

• Delimited by commas, apostrophes, or blanks. 
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When you code your command list with parameter variables, use the following 
guidelines: 

• You can use up to 31 parameter variables in a single command list. 

• You can use the same parameter variables more than once in a command list. 

• The value of a parameter variable can be 238 characters long. 

• Parameter variables can contain either numerical or character values. 

• A parameter variable can have a numerical value between -2147483647 and 
2147483647. 

Note: When NetView receives a message coded in an &wait statement, it sets the 
four control variables (&msgorigin, &msgio, &msgcnt, and &msgstr) and then 
changes the values of the parameter variables (&1 - &31) to reflect the information 
in the received message. See "Control Variables" on page 81 for information on 
these variables, linkpd sets the same control and parameter variables. See 
"LINKPD Results" on page 167 for more information on the linkpd command. 

Passing Variable Information to a Command List 

When activating a command list that uses parameter variables, the operator enters 
the command list name followed by a value for each parameter variable in the 
command list. Figure 39 shows the format for an operator passing up to 31 param- 
eter variables to a command list. 



cmdlistname 



&l &2 &3 &31 

Figure 39. Format for Passing Parameter Variables to a Command List 

The first value after the command list name replaces &1 in the command list, the 
next value replaces &2, and so on. For example, the second parameter variable in 
a command list would be coded &2 at the place where you want the value of that 
parameter. 

Assume that you wrote a command list named resc to start resource luioo as 
shown in Figure 40. 



RESC CLIST 

&C0NTR0L ERR 

VARY NET,ACT,ID=LU100 

Figure 40. RESC Command List to Start LU100 

If you want the command list to use parameter variables, you can change it to acti- 
vate or inactivate any resource. Figure 41 shows how the command list looks with 
parameter variables. 



RESC CLIST 
&C0NTROL ERR 
VARY NET,&1,ID=*2 

Figure 41. RESC Command List with Parameter Values 
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The operator can then start resource luioo by entering resc act.luioo. 

When the command list runs, &1 and &2 are replaced with the positional 
parameters: &1 with act, and &2 with luioo. The command list takes the values for 
&1 and &2 from the entered operands in the order in which the operands were 
entered after the command list name. 

Note: The operator who uses the command list must be told how many parameter 
variables to supply and what values to provide. For more information, see 
"&BEGWRITE Control Statement" on page 95. 

If a command list is activated by a message, each word of the message becomes a 
separate parameter variable. This is explained in more detail in Chapter 9, 
"Message Automation" on page 135. 

How Parameter Variables Are Used in the Command List 

There is no set order for placing the parameter variables in the command list. 
Figure 42 shows that you can use &2 before &1. 



V NET,&2,ID=&1 

Figure 42. Nonsequential Use of Parameter Variables in a Command List 

&1 is given the first value the operator enters, and &2 is given the second value. 

If there are two or more parameter variables in one command list statement, the 
rightmost variable is changed first. NetView continues to scan right to left and 
replaces the next variable. You can use this to change the meaning of some of 
your parameter variables. If you need to test how many parameters an operator 
entered or what parameter values were entered, use the control variables 
&parmcnt and &parmstr. They are described in "Control Variables" on page 81. 

Passing Parameter Variables to a Nested Command List 

You can code parameter variables on the command list statement that activates 
the nested command list. These parameter variables follow the same basic rules 
as other parameter variables. One added function is that you can pass either 
actual values or other variables as parameter variables. If you pass other vari- 
ables, make sure these variables are known to the next activated command list. 
Here are some examples of passing parameters. 

Command List caller contains a line of code such as: 

I CALLEE LINES JERMS,CDRMS 

Figure 43. Example of Passing Parameters 

Here is how command list callee picks up these variables: 

Variable Value 



61 LINES 

62 TERMS 

63 CDRMS 
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Command list major is activated by entering major alpha.beta and contains the fol- 
lowing statements: 



&A » 55 
MINOR &A,&1,&2 

Figure 44. Statements in MAJOR Example Command List 

Here is how command list minor picks up these variables: 

Variable Value 



&1 55 



62 ALPHA 

63 BETA 

Command list minor takes the value of &a (55) as its first parameter, the value of 
major's first parameter (alpha) as its second parameter, and the value of major's 
second parameter (beta) as its third parameter. 

Using Text Strings or Special Characters in Parameters 

If you need to use a blank, apostrophe, or comma as part of a value, you must 
make the value a special character string by using single quotes. If you want a text 
string to be taken as the value for one parameter, it must also be made a special 
character string. 

A special character string is any text that meets one of the following requirements: 

• Text that is preceded by a delimiter and a single quote, and is followed by 
either a single quote and a delimiter or a single quote that is the rightmost 
non-blank. 

• Text that is preceded by a single quote that is the leftmost non-blank, and is 
followed by a single quote and a delimiter 

• Text that is preceded by a single quote that is the leftmost non-blank, and is 
followed by a single quote that is the rightmost non-blank. 

Suppose you activate a command list named resc by entering the following: 
RESC ACT, ' LU2O0, L0GM0DE=S3270 ' 

The parameter variables in the resc command list would contain the following 
values: 

61 = ACT 

62 = LU200,L0GM0DE=S3270 

Now suppose you activated the resc command list by entering: 
RESC ACT,LU20O,LOGMODE=S3270 

The parameter variables in this case contain the values: 

61 = ACT 

62 = LU20O 

63 = LOGMODE=S3270 
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Null Parameter Values 

Use a comma immediately following another comma („) to give a parameter vari- 
able a null value when it is followed by other non-null parameters. After the last 
non-null parameter, all remaining parameter variables up to &31 are automatically 
given null values. Null parameters are useful when a value is not required. For 
example, assume you wrote a command list called conn that contained the fol- 
lowing statements: 



rBGNSESS 

j OPCTL,APPLID=&l,SRCVU=&2,SESSID=&3,L0GM0DE*&4 

Figure 45. Statements in CONN Example Command List 

If you do not want to specify all the values, you can enter the following: 

ICONN HCF,,SESSHCF 

Figure 46. Statement to Activate CONN Example Command List 

In this example, hcf is &1, &2 is null, sesshcf is &3, and &4 is null. The extra 
comma between hcf and sesshcf tells the command list that &2 is null and that 
sesshcf should be &3. If you only used one comma, the command list takes 
sesshcf for &2 and incorrectly uses sesshcf as the srclu. 

If you allow null parameter variables, you must test for them in your command list 
and provide default values. Otherwise, as in the example, the bgnsess command 
issued with srclu = null would get a syntax error. 

Control Variables 

Control variables are set by NetView based on system information. To use a 
control variable, place the variable name in the command list at the location where 
you want the information to be accessed. When the command list runs, NetView 
gives the correct values to each control variable. Use the listvar command to 
view the values of your variables (except for &parmcnt, &parmstr, and &retcode). 
For more information on listvar, see NetView Operation. 

The control variables let you obtain information about the operating environment, 
test conditions in the command list, and take actions based on the results. 

For more information on control variables used with the spcs commands linkdata 
and linktest, see "LINKDATA and LINKTEST Results" on page 166. 



Time and Date 



&DATE 

becomes the current date in the format mm/dd/yy, where mm is the month, dd 
is the day, and yy is the year. 

&TIME 

becomes the cpu time in the format hh:mm, where hh is the hour and mm is the 
minutes. The time is based on a 24-hour clock, so 3 o'clock p.m. is shown as 
15:00 (12:00 noon + 3:00 p.m. = 15:00). 
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Session Information 

&APPLID 



becomes the application program identifier for the task under which the 
command list is running, aapplid is always the NetView domain id appended 
with a 3-character alphanumeric value assigned by NetView. For example, if 
your domain id is paris, &applid might be parisool 

&NCCFCNT 

becomes the number of NetView domains with which the operator can estab- 
lish a cross-domain session. 

&OPSYSTEM 

becomes a character string that indicates the operating system for which 
NetView was compiled. &opsystem allows the same command list to run under 
different operating systems by allowing the command list to test for the type of 
operating system and process accordingly. &opsystem can contain the fol- 
lowing character values: 

MVS/XA 
VM. 

&TASK 

becomes the 3-character string ppt (primary poi task), ost (operator station 
task), or nnt (NetView-NetView task), depending on the task under which the 
command list is running. 

&task allows a command list to run under any of these tasks, because the 
command list can test for the task type and process accordingly. This is 
required because there are restrictions on command lists running under some 
tasks. See "Primary POI Task Restrictions" on page 17 for an example of 
these restrictions. 

&VTAM 

becomes a character string that indicates the level of the access method used. 
The variable is returned in one of two formats depending on whether the level 
of the access method includes a modification number. 

If the level of the access method does not include a modification number, the 
format of the variable is VTvr, where: 

VT - indicates the access method is VTAM 

v - indicates the version number of the access method 

r - indicates the release number of the access method. 

If the level of the access method includes a modification number, the format of 
the variable is Vvrm, where: 

V - indicates the access method is VTAM 

v - indicates the version number of the access method 

r - indicates the release number of the access method 

m - indicates the modification number of the access method. 

For example, for vtam Version 3 Release 2, the variable returns a value of VT32. 
For vtam Version 3 Release 1 Modification 1, the variable returns a value of 

V311. 

Note: The value of &vtam is null if vtam is not active. 
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Terminal Information 

&HCOPY 

becomes the name of the hard-copy log printer started by the operator. If there 
is no hard-copy printer for this operator, &hcopy is null. 

&LU 

becomes the logical unit name for the operator terminal. 

Operator Information 

&OPID 

becomes this operator's id. 

Command List Information 

&COMPNAME 

the 16-byte name of the component running when the command list was initi- 
ated. For example, if command list help is initiated, &compname defines the 
active component so that the correct help command list is initiated. &compname 
can contain the following character values: 

DSINCCF DSINCCF 
DSINPDA 
DSINLDM 
DSIVIEW 1 
DSIVIEW 3 
DSIVIEW 4 
DSIVIEW 5 
DSIVIEW 6 
DSIVIEW 7 
DSIVIEW 8 
DSIVIEW 9 
DSISTATMONRESUME 
DSILBROWSERESUME 
DSIVIEW APPL1 

&PARMCNT 

becomes the number of parameter variables entered when the command list 
was initiated. For example, if command list resc is initiated by entering resc 
ACT.LU200, then &parmcnt becomes 2. If there were no parameter variables, 
&parmcnt would be 0. 

&PARMSTR 

becomes the string of parameter values used when the command list was initi- 
ated. &parmstr does not include the command list name. For example, if 
command list resc is initiated by entering resc act,lu200, then &parmstr 
becomes act,lu200. If there are no parameter variables, &parmstr is null. 
&parmstr must not exceed 255 characters. 

&RETCODE 

is the return code set by either the most recent command processor or the 
most recently activated or nested command list. 

&retcode is initialized to zero. &retcode is set by a command processor or 
nested command list. When you write a command list that is called by another 
command list, you can set a return code on the &exit statement in the nested 
command list. You can use &retcode to test this return code in the calling 
command list. See "&EXIT Control Statement" on page 109. 
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On the &exit statement, you can set the return code to 0, -1, or a positive 
integer. NetView can set the return code to 0, -1, -2, or -3. You cannot code -2 
or -3 on the &exit statement, but you can test for them. Ail other negative 
return codes are reserved. 

Here are the possible values and meanings of &retcooe: 

Values Meaning 

No error. 

Positive integer You define the meaning. If &control err is in effect, the 

command is echoed to the screen. 

-1 An error was found. This command list and all nested 

command lists end. Message DSH97i is issued for this 
command list. 

-2 A command in the command list is not correct. The 

message DS12091 is displayed with the incorrect 
command. The command is ignored, and the command 
list continues. 

-3 A command in the command list is not in the operator's 

scope of commands. The incorrect command list state- 
ment is displayed along with message DS12101. The 
command is ignored, and the command list continues. 

-5 A command list is terminated as the result of a reset or 

other failure. 



Message Processing Information 
&MSGCNT 



is the number of elements of text in a message string. &msgcnt is used with 
&wait and with the linkpd command. 

See "Control and Parameter Variables Used with &WAIT" on page 116 for 
more information about using control variables with &wait. 

See "LINKPD Results" on page 167 for more information about the linkpd 
command. 

&MSGID 

is the message identifier of the message most recently received by NetView. 
The message identifier is the first token of the message (up to 10 characters). 
If the first token is longer than 10 characters, &msgid uses only the first 10 char- 
acters. If a reply id is sent with the message, it is not used as the first token. 
For an mlwto, &msgid uses the first token of the first line of the message. 
&msgid is used in message automation, with &wait, and with the linkpd 
command. See Chapter 9, "Message Automation" on page 135 for more infor- 
mation about message automation. 

See "Control and Parameter Variables Used with &WAIT" on page 116 for 
more information about using control variables with &wait. 

See "LINKPD Results" on page 167 for more information about the linkpd 
command. 

&MSGORIGIN 

is the domain where the message originated. &msgorigin is used for message 
automation, with &wait, and the linkpd command. 
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See Chapter 9, "Message Automation" on page 135 for more information 
about message automation. 

See "Control and Parameter Variables Used with &WAIT" on page 116 for 
more information about using control variables with &wait. 

See "LINKPD Results" on page 167 for more information about the linkpd 
command. 

&MSGSTR 

is the message text of the message most recently received by NetView. 
&msgstr does not include the message identifier (the token used by the &msgid 
control variable). &msgstr is used with &wait and with the linkpd command. 

See "Control and Parameter Variables Used with &WAIT" on page 116 for 
more information about using control variables with await. 

See "LINKPD Results" on page 167 for more information about the linkpd 
command. 

&SESSID 

is the taf session id where the message originated. &sessid is used in 
message automation and with &wait. See Chapter 9, "Message Automation" 
on page 135 for more information about message automation. 

Note: If taf starts a session with an &sessid equal to the domain id, &sessid will 
not be set correctly, and message automation may not work. 

The remainder of this section contains descriptions of control variables that are 
used only for message automation. More information on these control variables 
can be found in MVS Systems Programming Library: Systems Macros and Facili- 
ties, Vol. 2. 

Some of the message information control variables are filled with values only after 
NetView receives a message through the subsystem interface (ssi). The message 
information control variables that have null values until NetView receives a 
message through the ssi are: 

&AREAID 

&DESC 

&JOBNAME 

&JOBNUM 

&MCSFLAG 

&MSGTYP 

&ROUTCDE 

&SMSGID 

&SYSCONID 

&SYSID. 

&AREAID 

provides a one-letter (A-Z) identifier for the area on the console screen that 
displays the message. 

&DESC 

provides the system descriptor codes in a binary series of on (1) and off (0) 
characters, representing the descriptor code bits in order. 
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&HDRMTYPE 

provides the 1 -character NetView message type of the message. NetView 
message types are described in NetView Customization: Using Assembler. 

Note: &hdrmtype is a NetView-supplied message control variable. 

&JOBNAME 

provides the 1- to 8-character mvs job name identifier. Because the jobname is 
the name of the job that originated the message, it may not always be the 
same as the name of the job to which the message is referring. For example, 
this can occur when mvs issues a message about the NetView job. Also, 
jobname can contain the name of an initiator (instead of the actual jobname) 
when a job is started or terminated. If the message is issued during startup or 
termination, extract the job name from the message text rather than using the 
jobname variable. 

&JOBNUM 

provides the 8-character mvs job number identifier. Depending on the mvs 
release, sjobnum can be a character string such as 'job 4', or simply a 
number such as ' 4'. 

Note: The appropriate number of blanks are imbedded within jobnum to 
ensure a total length of 8 characters. 

&LINETYPE 

provides the multi-line write-to-operator (mlwto) line type, as follows: 

C The line is a message control line. 

L The line is a message label line. 

D The line is a message data line. 

DE The line is the last message data line. 

E The line is the last message line and contains no data. 

blank The message is a single-line message. 

&MCSFLAG 

provides the system message flags in a binary series of on (1) and off (0) codes 
corresponding to the following meanings: 

first Send message conditionally to console &sysconid 

second Send message unconditionally to console &sysconid 

third resp 

fourth REPLY 

fifth brdcst 

sixth hrdcpy only 

seventh notime 

eighth nocpy. 

&MSGTYP 

provides the system message type as three consecutive binary characters. An 
on character (1) in one of the positions corresponds to the following meanings: 

first sess 

second jobnames 
third status. 

&REPLYID 

provides a three-character reply identifier for wtor command replies. See 
"WTOR" on page 140 for more information about the wtor command. 
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&ROUTCDE 

provides the system routing codes in a binary series of on (1) and off (0) char- 
acters, representing the routing code bits in order. 

&SMSGID 

provides an 8-character value that identifies a particular instance of a 
message. This control variable is used by the dom command to identify action 
messages to be removed from the display. See "DOM" on page 141 for more 
information about dom. 

&SYSCONID 

provides the console number (in decimal) that receives the message. 

&SYSID 

provides the identifier of the mvs system that sent the message. 

&WTOREPLY 

is the reply sent by the operator in response to a wtor command. See 
"WTOR" on page 140 for more information about the wtor command. 



&VIEWAID 

returns the aid key that the operator used to enter panel input. 

The possible values and meanings for &viewaid are as follows: 

Values Meaning 

PF 1 - 24 Programmed function (PF) key. PF1, PF2, ...PF24. 

PA 1 - 3 Program access (PA) key. PA1, PA2, or PA3. 

ENTER The ENTER key. 

&VIEWCURCOL 

returns the panel column where the cursor was positioned when the aid key 
was pressed. 

&VIEWCURROW 

returns the panel row where the cursor was positioned when the aid key was 
pressed. 



User variables are variables you create and set within the command list. User var- 
iables are set with an assignment statement or an &pause control statement. 
Figure 47 shows the syntax of an assignment statement. 



&uservariable — expression 

Figure 47. Assignment Statement Syntax 

The user variable is set to the value of the expression. For example, &A = 3 sets 
the user variable &A to 3. You will learn more about assignment statements in 
"Assignment Statements" on page 90. 

The &pause control statement halts the command list, allows the operator to enter 
data, and picks up the value of the user variable from the operator when the 
command list continues. &pause is described in "&PAUSE Control Statement" on 
page 97. 
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When you create user variables, observe the following rules: 

• The first character must be an ampersand (&). 

• The first character following the ampersand must be a letter or a symbol, not a 
number. Otherwise, NetView treats it as a parameter variable. 

• The ampersand is followed by 1 to 11 characters. A-Z, 0-9, #, @, and $ are 
valid characters. 

• Double-byte character set (dbcs) variable names are not supported. All vari- 
able names must be written using Latin characters. See "Conventions for 
Double-Byte Character Set Text" on page 74 for more information about dbcs 
characters in command lists. 

• The value of the user variable can be 255 characters long. For dbcs charac- 
ters, the maximum number of double-byte characters between the shift-out and 
shift-in is 126. 

• You can give user variables a numerical value between -2147483647 and 
2147483647. The only characters you can use in a numerical value are 0-9. 
The numerical value can be immediately preceded by a character indicating 
whether the value is positive (+) or negative (-). 

Note: You can create a user variable that NetView has already defined as a 
control statement, control variable, or built-in function. However, you cannot use 
that NetView function in this command list. 

Table 2 shows some examples of user variable names. 

Table 2. Valid and Invalid User Variable Names 



Valid 


Invalid 


Reason Why Invalid 


&A 


&2A 


Will be read as &2, a param- 
eter variable 


&USERNAME 


&INVALIDUSERNAME 


Too long 



&@23456 &A% % is an invalid character 

Figure 48 shows how to manipulate user variables in assignment statements to set 
parameters and to communicate with the operator. 



&PAUSE VARS &0NE &TW0 

&SUM = &0NE + &TW0 

CLEAR 

&WRITE >» THE SUM OF &0NE + &TW0 IS — >&SUM 

Figure 48. User Variables in Command List Statements 
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Comments 



You will find it very helpful to code comments in a command list. Command lists 
with comments are easier to maintain and expand. 

You can use comments to show: 

• When the command list was created and updated 

• Who wrote the command list 

• The function of the command list 

• What input and output is expected 

• Whether this command list depends on other programs or on other command 
lists. 

To write a comment, code an asterisk (*) as the first non-blank character of the 
command list line. Ensure that you do not use a string of hyphens to separate 
sections of the command list. 

Figure 49 shows how comments are used for a title block and other internal doc- 
umentation. 



: *** 

*** CLIST: SAMPLE 

*** DATE: 1-2-87 BY: JANE DOE 
v *** PURPOSE: 

I *** SAMPLE CLIST TO SHOW USE OF CONCEPTS OF CHAPTER 2 IN THE 
i *** CLIST MANUAL 
! *** INPUT: 'SAMPLE' FOLLOWED BY A MESSAGE YOU WANT DISPLAYED 

*** ON THE TERMINAL 

; ' *** 

* *** FIRST ISSUE THE CLEAR COMMAND TO GIVE US A CLEAN SCREEN 
f CLEAR 

i *** NOW LETS SHOW THE USE OF &PARMSTR AND POSITIONAL VARIABLES, 
:*** AND THEN GET SOME USER INPUT... 

Figure 49. Comment Statements for Internal Documentation 



Null Statements 



Another type of command list statement is the null statement. A null statement 
contains all blanks or a label followed by all blanks. A null statement with a label 
can be the target of flow control (conditional processing) statements or &beqwrite 
statements. See "Labels" on page 75 for details about using labels. 

You can use a null statement to help format a message to the operator or to break 
up a long command list so that it is easier to read and update. If a null statement is 
part of a message written with an &begwrite statement, it is sent to the operator as 
a blank line. If a null statement is used to break up the command list, it is ignored 
by NetView when the command list is run. 
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Assignment Statements 



Assignment statements are used to give values to variables and do arithmetic 
operations within a command list. Figure 50 shows the syntax of an assignment 
statement: 



^variable = expression j 

Figure 50. Assignment Statement Syntax 

There must be a blank before and after the equal sign. 

When the command list runs, the value of the user variable is set to the value of 
the expression. For example, if you had the assignment statement &A = 5, the 
value of &A becomes 5. If you had the assignment statement &B = &1, the value 
of &B is set to the value of &1, and &1 keeps its value. 

An expression is one of the following: 

A Constant 

A constant consists of alphanumeric characters that are not replaced by 
other values. The values are fixed. For example, if you code the fol- 
lowing assignment statement: 

&VAR = 5 

the value 5 is assigned to user variable &var. 

If you want to use a constant string that contains a blank, comma, apos- 
trophe, or hyphen, make it a special character string by using single 
quotes. For example: 

&NAME = 'JOHN B. DOE' 

is a constant string containing blanks. 

The constant cannot be longer than 255 characters. If it is a number, 
the constant must be between -2147483647 and 2147483647. The only 
characters you can have in a numerical value are 0-9. The numerical 
value can be immediately preceded by a character indicating whether 
the value is positive (+) or negative (— ). 

A Variable 

A variable can be a parameter variable, control variable, user variable, 
or global variable. 

The following assignment statement: 

&PARMVAR = &4 

assigns the value of parameter variable &4 to user variable &parmvar. 

To assign the value of control variable &opid to user variable &uservar, 
code the following: 

&USERVAR = &0PID 
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Note: You cannot use a control statement as a variable, even if the 
control statement is enclosed in single quotes. For example, you could 
not have the following assignment statements: 

&A = &IF 

&A = '&WAIT ERROR' 

An Arithmetic Operation 

The addition and subtraction operations are allowed in an assignment 
statement. The format is two numbers separated by a plus (+) or minus 
(-) sign. You can also use a variable that will be set to a number. The 
only characters you can use in a numerical value are 0-9. The numer- 
ical value can be immediately preceded by a character indicating 
whether the value is positive (+) or negative (— ). 

The plus or minus sign must be separated from the numbers on each 
side by at least one blank unless it indicates a positive or negative 
number (-2, -4). For example, both 4-2 and 4 - -2 are correct, but 4 -2 
will not work. 

The results of the arithmetic operation must be between -2147483647 
and 2147483647. 

The following assignment statement shows how you can use a control 
variable in an arithmetic operation: 

&SUM = 38 - &PARMCNT 

The value of control variable &parmcnt is subtracted from 38, and the 
resulting value is assigned to user variable &sum. 

In arithmetic expressions with leading zeros, the leading zeros are not 
shown in the result. For example, assume &A is 01 and you code the 
following: 

&C = &A + 1 

The value of &C becomes 2, not 02. 

A Built-in Function 

A built-in function can be used in an assignment statement. The result 
of the operation is placed in the user variable. See "Built-in Functions" 
on page 99 for a detailed description. 

The following examples show how to code built-in functions in assign- 
ment statements: 

&STR2 = &SUBSTR &STRING 2 1 
&STR1 = &SUBSTR &STRING 1 1 
&NEWSTR = &C0NCAT &STR5 &STR4 
&NEWSTR = &C0NCAT &NEWSTR &STR3 

To review a command list that contains all of the concepts covered in this chapter, 
see "Sample Command List—Chapter Review" on page 105. 
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Control Statements 

Control statements are unique command list statements that the way NetView acts 
on other statements in the command list. The control statements in this chapter 
can be used for either straight-line coding or in conjunction with the statements 
described in Chapter 7, "NetView Command List Language Branching" on 
page 107 for structured conditional processing. 

The NetView command list language lets you use structured programming tech- 
niques in writing your automation applications. You can use control statements to 
to change the strict sequential order of processing. Command list control state- 
ments allow you to do the following: 

• Send messages to the operator from the command list 

• Control the order in which commands are run 

• Ask the operator to enter information needed to continue the command list 

• Wait for a solicited message to arrive before continuing the command list. 

Each command list control statement begins with the control symbol in the form 
&word. Only one control statement can be coded on a line, except when using &if. 

After reading the descriptions of the control statements, you should have a general 
idea of the capability of these basic statements. Read the sections that follow for 
details concerning each control statement. 

The control statements are: 

&CONTROL 

indicates the command list statements shown on the operator's screen while 
the command list is running. 

&WRITE 

writes a message to the designated operator. 

&BEGWRITE 

writes a message or series of messages to the operator. &begwrite is a short- 
ened form of begin writing. 

&PAUSE 

halts the command list until the operator enters information needed to continue 
the command list. 

&CONTROL Control Statement 

&control lets you indicate which command list statements are displayed at the 
operator's terminal while the command list is running. The indicated command list 
statements are displayed after all substitutions have been made and before the 
command list statements run. The display of the command list statements from 
&control all or &control cmd can be used to help debug your command list. 

Set &control at the beginning of the command list. You can change the &control 
setting within the command list as many times as necessary. &control is in effect 
from that point in the command list until the next &control statement is reached. 
For instance, if you just added a new section of code to a command list, you can 
display the entire new section of code but view only the errors for the existing 
sections of code. Code this control statement by typing &control followed by a 
blank and then by an operand. Figure 51 on page 93 shows the syntax of the 
&control control statement. 
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f ^CONTROL [ALLjCMDIERR] 

Figure 51. &CONTROL Control Statement Syntax 

&CONTROL ALL 

displays all command list statements at the operator's terminal. Each state- 
ment is displayed just before it is processed. This is a good choice when you 
first write the command list and want to test it. Once your command list is 
tested, &control cmd or &control err is a better choice. When processing for 
this command list is complete, message DS10131, command list ciistname complete 
is displayed. If you code &control without any operands, or if you do not code 
&control, &control all is the default. 

&CONTROL CMD 

displays all commands at the operator's terminal. Each command is displayed 
just before it runs. The other command list statements— such as comments, 
control statements, and other command list language statements— are not dis- 
played unless they contain an error. When processing for this command list is 
complete, message DS10131, command list ciistname complete is displayed. 

&CONTROL ERR 

displays only statements that contain errors and commands that have non-zero 
return codes. If &control err is in effect at the end of a command list, 
message DS10131 is not displayed. 

The control statement, &control err, is coded in "Sample Command List— Chapter 
Review" on page 105 for displaying incorrect statements and those commands 
with non-zero return codes. 

Writing to the Operator 

&write and &begwrite send messages to the operator terminal. &write only sends a 
one line message, whereas &begwrite allows multi-line messages to be sent. 
These statements are used, for example, to tell the operator what the command list 
is doing. 

The messages are sent to the operator regardless of the &control setting. If you 
code a command on an &write control statement, the text is sent to the operator as 
a message, but it is not run as a command list command. 

Do not confuse the use of &write and &begwrite with the use of command list com- 
ments. Comments are for the person writing the command list and are not sent to 
the operator unless &control all is set; &write and &begwrite send messages to 
the operator. 

if you are sending more than one message line or displaying a table that takes up 
the whole screen, you might want to issue the NetView clear command first. The 
clear command erases the screen and causes whatever you are writing to the 
operator to begin at the top of the screen. If you do not want commands and 
control statements that complete correctly to be displayed with what you are 
writing to the operator, make sure &control err is in effect before issuing the 
clear command. 
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&WRITE Control Statement 

&write sends one line of text to the operator. NetView performs variable substi- 
tution on the message text before sending the message to the operator. If you do 
not want substitution performed on the message text, use &begwrite. If you do not 
include message text, NetView sends a blank line to the operator. The syntax for 
&write statements is shown in Figure 52. 



&WRITE message text I 

Figure 52. &WRITE Control Statement Syntax 

If you want to include blanks in front of the first character of the line, code a non- 
blank character after &write. 

The period causes this line: 

&WRITE . THIS LINE WILL START IN COLUMN 8 

to print like this: 

THIS LINE WILL START IN COLUMN 8 

Otherwise, the line will shift left until the first non-blank character is in column 1. 

The following line has no period: 

&WRITE THIS LINE WILL SHIFT TO COLUMN 1 

so it prints like this: 

THIS LINE WILL SHIFT TO COLUMN 1 

Figure 53 is an example of a command list called path that uses the &write control 
statement and a vtam command. 



PATH CLIST | 

&C0NTR0L CMD j 

* THIS COMMAND LIST DISPLAYS INFO ON VTAM SWITCHED PATHS | 

&WRITE *** STATUS OF VTAM SWITCHED PATHS FOR &1 *** | 

D NET, PATHS, ID=&1 I 

Figure 53. Example Command List Using &WRITE 

Activating this command list by entering path HD3790N1 causes the operator to see a 
display similar to the following. 



*** STATUS OF VTAM SWITCHED PATHS FOR HD3790N1 *** 

D NET,PATHS,ID=HD3790N1 

IST097I DISPLAY ACCEPTED 

IST148I DIAL OUT PATH INFORMATION FOR PHYSICAL UNIT HD3790NI 

IST149I LINE GRP TELEPHONE NUMBER OR LINE NAME PID SID CNT 

IST168I EGROUP40 4094 001 001 005 AVA 

AUT 

IST168I E6ROUP50 4094 002 002 001 AVA 

MAN 

IST314I END 

Figure 54. Result of PATH Example Command List 
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Notice that the &1 in the &write statement is replaced by the value HD3790N1 before it 
is sent to the operator. Because &control cmd was coded, the command is also 
shown. The rest of the display is the response to the vtam command. 

Figure 55 shows several &write statements, which send one-line messages to the 
operator. 



| CLEAR 

[: &WRITE >» THE SUM OF &0NE + &TW0 IS — >&SUM 

ft &WRITE THE MIRROR IMAGE IS: &HEWSTR 

f 

I &WRITE TOTAL CHARACTERS ENTERED: &LEN 

&WRITE *** END OF SAMPLE CLIST, BYE *** 

Figure 55. &WRITE Statements to Send Operator Messages 



&BEGWRITE Control Statement 

You can use &begwrite to write a series of lines to the operator terminal. You can 
also control whether variables are replaced before sending the messages. The 
syntax for &begwrite statements is shown in Figure 56. 



&BEGWRITE [SUB|NOSUB][-/abe/] 

Figure 56. &BEGWRITE Control Statement Syntax 

&begwrite is coded differently than &write. You code &begwrite on a line by itself, 
one line above the first operator message you wish to send. You can also specify a 
label on &begwrite. The label tells the command list where the messages end and 
command list processing continues. See "Labels" on page 75 for more informa- 
tion about labels. 

You can indicate that you want variables replaced by their actual values before the 
messages are sent to the operator. If you do not indicate a choice, variables are 
not replaced. 

&BEGWRITE SUB -label 

causes NetView to carry out substitution on the message text before sending 
the messages to the operator. See "Variable Substitution Order" on page 76 
for information on how NetView carries out variable substitution. 

If there are blanks before the first character on a message line, the line is 
shifted left until the first non-blank character is in column 1. If you want the 
blanks sent to the operator's screen, code a nonblank character in column 1. If 
you are using &begwrite to write a message containing double-byte character 
set (dbcs) characters, you must use the sub option. These coding rules are the 
same as those for &write. 

&BEGWRITE NOSUB -label 

writes the messages to the operator exactly as they are typed, with no variable 
substitution. In other words, &1 is sent as &1, not as the value of &1. Use this 
operand to write about the command list variables in your messages, nosub 
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does not remove blanks. It displays the text exactly as it is entered. If you 
code &BEGWRITE without an operand, NetView assumes nosub. 

-label 

indicates the line that follows the text to be displayed to the operator. If you 
code a label in the statement, this label must be on a statement following the 
end of the message text lines in the command list. The command list lines 
between &begwrite and the statement with the label are sent to the operator. 
The command list statement with the label is not sent to the operator; it is proc- 
essed as the next command list statement. If NetView cannot find the label, the 
rest of the command list statements are sent to the operator as comments and 
the command list is ended. If there is no label on &begwrite, only the first 
command list statement after &begwrite is sent to the operator. 

You can code a variable for your label on &begwrite, but make sure the vari- 
able is replaced by a valid value. 

Figure 57 shows an example of &begwrite with variable substitution. 



&BEGWRITE SUB -ENDTEXT 

>» HELLO &0P. 

>» YOU CAN INITIATE CROSS-DOMAIN SESSIONS WITH &ID. 

.NOW FOR SOME CHARACTER MANIPULATION 
ENTER , 60» FOLLOWED BY A FIVE CHARACTER STRING. 
THE CLIST WILL PRINT OUT THE MIRROR IMAGE TO YOU. 

-ENDTEXT 

Figure 57. &BEGWRITE with Variable Substitution 

In some cases, you might not want variable substitution. In Figure 58, the 
&begwrite shows the operator how to use the endit command list. 



&C0NTR0L ERR 
&BEGWRITE NOSUB -OVER 
TO ENO FULL SCREEN SESSIONS, 
TYPE "ENDIT &1,&2,&3" 
REPLACE &1,&2,&3 WITH 
THE APPLID NAMES OF THE 
FLSCN SESSIONS TO BE ENDED 
-OVER 

Figure 58. &BEGWRITE with No Variable Substitution 
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The endit command list is called by entering endit. The operator sees the following 
messages: 



I TO END FULL SCREEN SESSIONS, 
6 TYPE "ENDIT &1.&2.&3" 
I REPLACE il,&2,*3 WITH 
i THE APPLID NAMES OF THE 
| FLSCN SESSIONS TO BE ENDEO 

Figure 59. Result of ENDIT Example Command List 

Notice that &1, &2, and &3 are not replaced by their values when the messages are 
sent to the operator. 

&PAUSE Control Statement 

Using the &pause control statement along with other commands, you can code 
command lists that ask the operator questions and pick up the entered responses. 
Use the &begwrite and &write control statements to send instructions to the oper- 
ator. For example, you can code the command list to instruct the operator to enter 
the NetView go command followed by a value or values for a user variable. Then 
code the &pause statement to temporarily halt the command list. The command list 
pauses until the operator enters the go command to continue processing or the 
reset command to end the command list. The &pause command can be coded to 
allow the command list to pick up the operands following the GO commands and 
take them as user variables. See "User Variables" on page 87 for more informa- 
tion about this subject. 

Note: There are times when you cannot use &pause. Do not use &pause in an auto- 
mation task command list or a command list that runs under the Primary poi Task 
(ppt). For more information about automation task command lists, see "NetView 
Release 3 Automation Task" on page 136. For more information on ppt 
restrictions, see "Primary POI Task Restrictions" on page 17. 

You can code &pause three different ways. Figure 60 shows the syntax for &pause 
statements. 



&PAUSE rNOlNPUTl VARS variable [,..]|STRING variable 1 } 

Figure 60. &PAUSE Control Statement Syntax 

&PAUSE NOINPUT 

pauses until the operator enters the go or reset command. No operands are 
allowed with the go command. If the operator enters operands, an error 
message is displayed. If you code &pause without any operands, &pause 
noinput is assumed. 

&PAUSE VARS variable [...] 

pauses until the operator enters the go command with or without the correct 
number of operands, or the reset command. The operator is told by a previous 
&write or &begwrite statement to enter operands with the go command. Each 
operand is taken as a user variable coded on the &pause vars statement. 
These variables can then be used in the command list. 
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&PAUSE STRING variable 

pauses until the operator enters the go command with or without a string, or 
the reset command. The operator is told by a previous &write or abegwrite 
statement to enter operands with the go command. The entire string of oper- 
ands is taken as one user variable. The variable can then be used in the 
command lists. 

When the command list interprets an &pause control statement, NetView puts the 
letter p on the upper right-hand corner of the terminal screen to show the operator 
that the command list is in pause state. Pause state means that the command list 
has halted and is waiting for input from the terminal. 

Note: If a command list in pause state was called by an nnt session, the p indi- 
cator is not displayed on the ost screen. 

Using NetView Commands with &PAUSE 

The operator can enter the NetView commands go, reset, stack, and unstack 
during a pause. See NetView Operation for details of these network commands. 

stack and unstack let the operator suspend and then resume command list proc- 
essing during an &pause. Once the stack is issued, the operator can enter any 
network commands. 

Note: While an &pause is suspended with the stack command, the p is removed 
from the upper right-hand corner of the screen. The p reappears after unstack is 
issued. After unstack is issued, the operator enters go either with or without oper- 
ands to continue the command list, or enters the reset command to end the 
command list, reset also ends any nested command lists. 

The operands on the go command are positional. This means the first operand 
becomes the first user variable, the second operand becomes the second user var- 
iable, and so on. Operands are separated by either a blank or a comma. If you 
want to include a blank or a comma as part of one variable, use either &pause 
string or put the operand between single quotes. 

You should code a user variable for each expected operand. If the operator enters 
more operands on the go command than expected by the command list, the extra 
operands are ignored. If the operator enters fewer operands than expected, the 
remaining variables are set to null. The operator can also skip over one operand 
by coding two commas in a row. 

You should always precede pauses for operator input with messages telling the 
operator what to enter. Use the &write or &begwrite statements to send this infor- 
mation. 

Note: It is important to remember that the operator can invoke your command list 
from any NetView component. If you expect the command list to run from compo- 
nents other than the command facility, use the NetView command nccf in the 
command lists to present the operator with the command facility screen and 
command screen input area. (Do this before issuing any messages.) If the 
command list is running in the command facility, the nccf command has no effect. 
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An Example Using &PAUSE 

Figure 61 contains a portion of a command list that shows how you can ask for 
information from an operator. 



* &BEGWRITE SUB -ENDTEXT 

[ . ENTER 'GO' FOLLOWED BY YOUR LAST NAME, 

I . FIRST NAME, AND MIDDLE INITIAL. 

I -ENDTEXT 

i * GET THE INPUT FROM THE USER 

! &PAUSE VARS &LAST &FIRST &MI 

Figure 61. Example &PAUSE Statement 

The example writes a message to the operator asking for the operator's last name, 
first name, and middle initial. The command list pauses until the operator enters a 
go or reset command. To continue processing the current command list, the oper- 
ator enters the go command followed by the string required by the command list. 

If the operator enters: 

GO SMITH JOHN A 

the value of &last becomes smith, the value of &first becomes john, and the value 
of &mi becomes a. These variables can then be used by other statements in the 
command list. 
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Built-in functions perform predefined operations. They are used as expressions 
either in an assignment statement or in an &if control statement. See "&IF Control 
Statement" on page 107 for information on the &if control statement. In an assign- 
ment statement, the value of the user variable is set to the result of the built-in 
function's operation. 

Be careful not to confuse built-in functions with variables. Although they appear 
similar, they are not the same. A built-in function looks like a variable because 
they both start with an ampersand (&). Here is the difference: 

• A variable is replaced by its value when the command list runs. The variable 
is really just a place holder for the value. 

• A built-in function is never replaced by a value. It is an action indicator rather 
than a place holder. 

These are the built-in functions you can use: 

• &CONCAT 

• &LENGTH 

• &NCCFID 

• &NCCFSTAT 

• &SUBSTR. 
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Figure 62 shows the format to use for coding built-in functions for an assignment 
statement. 



&uservariable = Built-in Function {&variabfe\con$tant} 1 

Figure 62. Syntax for Coding Built-in Functions in an Assignment Statement 

The examples in this section use built-in functions in assignment statements. 
Examples with built-in functions in the &if control statement are in "&IF Control 
Statement" on page 107. 

In an &if control statement, the result of the built-in function is used as one or both 
of the compared expressions. For example, you might use the &length built-in 
function to compare the lengths of two variables. 

&CONCAT Built-in Function 

&concat concatenates the values of two variables, two constants, or a variable and 
a constant to form a new value. &concat is a shortened form of concatenate. The 
syntax of the &concat built-in function is shown in Figure 63. 

buservariable = &CONCAT {&variable\constant} {&variable\con$tant} 

Figure 63. Syntax for &CONCAT in Assignment Statements 

Ensure that when the two items are joined, the resulting value does not exceed 255 
characters. If the combined value exceeds 255 characters, it is truncated to 255 
characters. If the value of both items being joined is null, the value of 
&uservariable is null. 

When &concat is used to concatenate two double-byte character set (dbcs) strings 
it removes adjacent shift-in (Si) and shift-out (so) characters. 

Figure 64 shows how &concat is coded to concatenate the values of five variables 
into one new variable. 



&NEWSTR = &C0NCAT &STR5 &STR4 
&NEWSTR = &C0NCAT &NEWSTR &STR3 
&NEWSTR * &C0NCAT &NEWSTR &STR2 
&NEWSTR = &C0NCAT &NEWSTR &STR1 

Figure 64. &CONCAT Function to Build a Character String 



&LENGTH Built-in Function 

&LENGTH returns the length of a variable or a constant. Figure 65 shows the syntax 

Of &LENGTH. 



&uservariable - &LENGTH {&variable\constant } 
Figure 65. Syntax of &LENGTH in Assignment Statements 
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The value of Auservariable is set to the length of the constant or variable. If the 
variable on the right of the equal sign is null, the length is 0, and the value of the 
user variable becomes 0. 

Figure 66 is an example of you how to use &length. Suppose you called command 
list samp by entering samp LU2525. Assume the name of the hard-copy printer 
(&hcopy) control variable was HC55. 



f SAMP CLIST 

I &HCLENGTH = &LENGTH &HC0PY 

| &RESLEN = &LEN6TH &1 

Figure 66. Example Command List Using &LENGTH 

After processing, the variable settings are: 

Variable Value 



&HCOPY 


HC55 


&HCLENGTH 


4 


&1 


LU2525 



&RESLEN 6 

User variable &hclength is set to the length of the hard-copy device name. The 
hard-copy device is HC55. HC55 has four characters, so &hclength becomes 4. 
&reslen becomes the length of the first parameter variable. The first parameter 
variable is LU2525, so &reslen becomes 6. 

&NCCFID Built-in Function 

&nccfid indicates the NetView domain identifier of a domain with which you can 
establish a cross-domain session. The value of &nccfid is not necessarily the 
domain identifier of your domain. To use this built-in function, code &nccfid fol- 
lowed by a number. For more information on defining domains to NetView, see 
NetView Installation and Administration Guide and NetView Administration Refer- 
ence. 

The command list can use &nccfid to automatically start or stop a cross-domain 
session. Figure 67 shows the syntax of nccfid. 



?." &uservariable = &NCCFID number 

Figure 67. Syntax for &NCCFID in Assignment Statements 

The number is either a constant or a variable. The largest number permitted is the 
value of &nccfcnt, the control variable that shows the total number of cross- 
domain sessions this operator can start. 

Figure 68 on page 102 is an example of you how to use &nccfic. 
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&D0M1 = &NCCFID 1 
&00M2 - &NCCFID 2 
&D0M3 = &NCCFI0 a 
START D0MAIN=&D0M1 
START D0MAIN=&D0M2 
START D0MAIN=&D0M3 

Figure 68. Using &NCCFID Function to Start a Cross-Domain Session 

Assume the domains table has these entries: 

1 ALPHA 



BETA 



3 GAMMA 

After processing, the user variables are set as follows: 
Variable Value 



&DOM1 ALPHA 

&DOM2 BETA 

&DOM3 GAMMA 

The command list uses &nccfid to index the first three entries of the domains table. 
&DOM1 is set to alpha, the first domain listed. &DOM2 is set to beta, the second 
domain. &DOM3 is set to the third domain, gamma. These three domains are then 
started with the NetView start command. 

In this example, the operator must know there are three domains that can be 
started. You can also use the &if control statement to test &nccfcnt to find the 
number of domains and start them. 

&NCCFSTAT Built-in Function 

&nccfstat indicates whether you have an active cross-domain session with a 
domain. Figure 69 shows the syntax of &nccfstat. 



&uservariable = &NCCFSTAT domain 

■■•■■• ••'I 

Figure 69. Syntax for &NCCFSTAT in Assignment Statements 

In this case, domain is either a domain name or a variable that becomes a domain 
name. 

The &uservariable variable is replaced by the characters act if the operator has an 
active cross-domain session with the domain. The user variable is replaced by the 
characters inact if the operator does not have an active cross-domain session with 
the domain. 

For example, you can write a command list to check the status of a domain and 
start that domain if it is not active. Assume you activated the startem command 
list in Figure 70 on page 103 by entering startem nccfa. 
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STARTEM CLIST 
■ &C0NTR0L ERR 
&STATUS = &NCCFSTAT &1 
&IF &STATUS = INACT &THEN START D0MAIN=&1 
&IF &STATUS = ACT &THEN &WRITE DOMAIN &1 IS ALREADY ACTIVE 

Figure 70. Example Command List Using &NCCFSTAT 

After processing, the variables are set as follows: 

Variable Value 



&1 NCCFA 

&STATUS ACT|INACT 

The parameter variable &1 is set to nccfa, and the status of domain nccfa is 
checked. If you have an active cross-domain session with nccfa, &status is set to 
act. If not, &status is set to inact. The &if statement tests whether &status is set to 
act or inact (for more information, see "&IF Control Statement" on page 107). 

If nccfa is inactive, the command list starts it. If nccfa is active, you receive this 
message: 

DOMAIN NCCFA IS ALREADY ACTIVE 

&SUBSTR Built-in Function 

&substr uses part of a variable to form the value of a new user variable. &substr is 
a shortened form of substring. Figure 71 shows the syntax of &substr. 

&uservariable - &SUBSTR &variabie start {length'] 

Figure 71. Syntax for &SUBSTR in Assignment Statements 

&substr takes the variable and starts at position start for length characters. 
Suppose you had the following statements: 

&H0LD = ACF/VTAM 

&FIRST = &SUBSTR &H0LD 1 3 

&SEC0ND = &SUBSTR &H0LD 5 4 

Figure 72. Example Command List Using &SUBSTR 

After processing, the user variables are set as follows: 

Variable Value 



&HOLD ACF/VTAM 

&FIRST ACF 

&SECOND VTAM 



The first line of Figure 72 sets the value of variable &hold to acf/vtam. In the next 
line, &substr starts at the first character of &hold (the letter a) and moves three 

Chapter 6. Simple NetView Command List Language Command Lists 103 



NetView Command List Language Command Lists 



characters to the right (to the character f). The letters acf become the value of the 
variable &first. In the last line, &substr starts at the fifth character of &hold (the 
letter v) and goes for a length of four (to the character m). The letters vtam are put 
into variable &second. The starting positions are determined as shown: 

1 2 3 4 5 6 7 8 



M 



Note: The first starting position is 1, the second is 2, and so on. Zero is not a valid 
position. Because the largest variable value is 255 characters, it is invalid to have 
a starting point greater than 255. 

You do not have to specify a length. If the length is not specified, the remainder of 
the string to the right beginning with the starting position becomes the substring. 
NetView never pads substrings with blanks. If you specify a length that is too long, 
NetView assumes no length was specified and uses the entire string beginning at 
the starting position. If the length is 0, or the starting position is beyond the vari- 
able length, the result of &substr is null. 

Figure 73 shows how you can use a substring of the &applid control variable to 
determine the name of the domain running the command list. 



GETDGMID CLIST 
&C0NTR0L ERR 

* DETERMINE THE LENGTH OF THE APPL ID 
&LENAPPL = &LENGTH &APPLID 

* SUBTRACT 3 TO GET THE LENGTH OF THE DOMAIN ID 
&LENAPPL - &LENAPPL - 3 

* START AT COLUMN 1 OF NEW LENAPPL FOR LENGTH OF DOMAIN ID 

* THE VALUE OF &D0MAIN WILL BE THE DOMAIN ID 
&D0MAIN = &SUBSTR &APPLID 1 &LENAPPL 

* &D0MAIN NOW CONTAINS THE DOMAIN ID 

Figure 73. Using &SUBSTR to Find the Domain Name from &APPLID 

Using &SUBSTR with DBCS Characters 

When using double-byte character set characters along with Latin characters (A-Z; 
a-z), &substr will adjust the variable as follows: 

Start byte = shift-out character No adjustment 

Start byte = shift-in character Replace by blank 

Start byte = first half of double-byte Replace by blank and shift-out 

character 

Start byte = second half of double-byte Replace by shift-out character 

Last byte = shift-out character Replace by blank 

Last byte = shift-in character No adjustment 

Last byte = first half of double-byte Replace by shift-in character 

Last byte = second half of double-byte Replace by shift-in character 

and blank. 
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Following is an example of the &substr statement used on a double-byte character 
set (dbcs) and Latin character string: 

&DBCS = 'AB<D1D2D3>EFG' 

where a, b. e, f, g are Latin characters, < is the shift-out character, > is the shift-in 
character, and di, D2, D3 are double-byte characters. Using this value, &substr 
works like this: 

&FIRST= &SUBSTR &DBCS 1 3 

= 'AB<' (interim string) 
= 'AB ' (recovery string) 

&SEC0ND = &SUBSTR &DBCS 3 5 

= '<D1D2' (interim string) 
= '<D1> ' (recovery string) 

&THIRD = &SUBSTR &DBCS 4 5 

= 'D1D2D' (interim string) 
= ' <D2D' (interim string) 
= ' <D2>' (recovery string) 

Note: The dbcs delimiters are 1 byte long; the dbcs codes are 2 bytes long. 



Sample Command List— Chapter Review 



^SAMPLE CLIST 

: &C0NTR0L ERR 

■ *************************************************************** 

|;" *** 

[.*** CLIST: SAMPLE 

; *** DATE: 1-2-87 BY: JANE DOE 

^ *** PURPOSE: 

*** SAMPLE CLIST TO SHOW USE OF CONCEPTS OF CHAPTER 6 IN 
[ *** NETVIEW CUSTOMIZATION: WRITING COMMAND LISTS 

[• *** INPUT: 'SAMPLE' FOLLOWED BY A MESSAGE YOU WANT DISPLAYED 
r *** 0N THE TERMINAL 

r ****************************************************************** 
i *** 

I *** FIRST ISSUE THE CLEAR COMMAND TO GIVE US A CLEAN SCREEN 

I CLEAR 

r *** NOW LETS SHOW THE USE OF &PARMSTR AND POSITIONAL VARIABLES, 

i *** AND THEN GET SOME USER INPUT... 

: &BEGWRITE SUB -ENDWRITE 

I ****************************************************************** 

|. *** 

|. *** &PARMSTR 

I *** &i u &3 &4 &5 

I *** &6 &7 &8 &9 m 

I *** &11 &12 &13 &14 &15 

L ****************************************************************** 

I ■■ ..... ..-: •• • ..... ■'.... ' ; ' ... ■. 

Figure 74 (Part 1 of 2). Review Command List 
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HI, THIS IS A MANIPULATION CLIST 
&TIME &DATE 

ENTER 'GO' FOLLOWED BY TWO NUMBERS 

AND THIS CLIST WILL RETURN THE SUM 

-ENDWRITE 

&PAUSE VARS &ONE &TWO 

&SUM - &ONE + &TWO 

CLEAR 

&WRITE >» THE SUM OF &ONE + &TWO IS — > &SUM 
* 

*** LETS DEMONSTRATE THE USE OF SOME CONTROL VARIABLES 
*** THEN ASK FOR MORE USER INPUT 

&ID = &NCCFID 1 

&OP = &OPID 

&BEGWRITE SUB -ENDTEXT 

>» HELLO &OP. 

>» YOU CAN INITIATE CROSS-DOMAIN SESSIONS WITH &ID. 

NOW FOR SOME CHARACTER MANIPULATION 

ENTER 'GO' FOLLOWED BY A FIVE-CHARACTER STRING. 

THE CLIST WILL PRINT OUT THE MIRROR IMAGE TO YOU. 

-ENDTEXT 
*** 

*** GET THE INPUT FROM THE USER 

&PAUSE VARS &STRING 

*** REVERSE FIVE CHARACTERS BY SEPARATING THE CHARACTERS 

*** USING THE &SUBSTR FUNCTION THEN RECOMBINING THEM USING 

*** THE &CONCAT FUNCTION 
*** 

&STR5 = &SUBSTR &STRING 5 1 

&STR4 = &SUBSTR &STRING 4 1 

&STR3 = &SUBSTR &STRING 3 1 

&STR2 = &SUBSTR &STRING 2 1 

&STRI = &SUBSTR &STRING 1 1 

&NEWSTR - &CONCAT &STR5 &STR4 

&NEWSTR - &CONCAT &NEWSTR &STR3 

&NEWSTR = &CONCAT &NEWSTR &STR2 

&NEWSTR = &CONCAT &NEWSTR &STR1 
*** 

&WRITE THE MIRROR IMAGE IS: &NEWSTR 
*** 

*** TELL THEM HOW MANY CHARACTERS WERE ENTERED 
*** BY USING THE &LENGTH FUNCTION 

&LEN = &LENGTH &STRING 

&WRITE TOTAL CHARACTERS ENTERED: &LEN 
*** 

*** LET THE USER KNOW THIS CLIST IS DONE 
&WRITE *** END OF SAMPLE CLIST, BYE *** 
&EXIT 

Figure 74 (Part 2 of 2). Review Command List 
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Chapter 7. NetView Command List Language Branching 

This chapter guides you through the NetView command list language features that 
let you code conditional and unconditional branching logic in command lists. 

The &if statement allows you to perform conditional branching based on logical or 
arithmetical comparisons. The result of a test or comparison in an &if statement 
determines which alternative to perform. Conditional processing statements give 
you the flexibility to code if-then and loop structures. 

The &goto statement allows you to perform unconditional branching. 

The &exit statement lets you code logical exit points within a command list. 

The &wait statement allows you to wait for expected events before processing con- 
tinues. 

See "Examples Comparing REXX and NetView Command List Language" on 
page 193 for samples of NetView command list language command lists that show 
how these control statements can be used. The equivalent rexx command lists are 
also included. 



&IF Control Statement 



You can initiate a conditional branch by coding an &if control statement. The &if 
control statement lets you specify processing based on a certain condition. The 
condition is formed with two expressions and a logical or arithmetical operator. 

A logical or arithmetical expression is evaluated while processing the &if state- 
ment. When the condition is true, the &then clause is processed. When the condi- 
tion is false, processing continues at the statement following the &if control 
statement. Figure 75 shows the syntax of the &if control statement: 



&IF comparison &THEN statement 
Figure 75. &IF Control Statement Syntax 

comparison 

The comparison clause is in the form: expressionl symbol expression2. 

expressionl is any expression that can be used in an assignment statement. 
It can be a constant, a variable, an arithmetic operation, or a 
built-in function. For more information on these, see "Assign- 
ment Statements" on page 90. 

symbol stands for the logical or arithmetical operator in the comparison 

clause. It is coded with one of the following mathematical 
symbols: 

Symbol Meaning 

= (or eq) Equal 

-.= (orNE) Not equal 

< (or lt) Less than 

> (or gt) Greater than 
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<= (or le) Less than or equal 

>= (or ge) Greater than or equal 

-.> (orNG) Not greater than 

-i< (or nl) Not less than 

Note: You can use either the symbol code or the 2-character 
letter code. Both mean the same thing. 

expression2 is the second term of comparison. It follows the same rules as 
expression"!. 

&THEN 

separates the comparison from the command list statement that is processed if 
the condition is true. You must code &then in every &if statement. 

Note: Be sure to code the ampersand (&) with &then. The ampersand identi- 
fies the word as part of the control statement. 

statement 

The command list statement that is processed if the comparison is true. If the 
comparison is not true, this statement is ignored. The statement can be any 
NetView command list statement. 

Variables coded in the comparison expressions are replaced by their values before 
the comparison is checked. If the variable has a null value, you get an error. For 
example, if you code the expression &a = &b, and &b is null, NetView cannot do the 
comparison. To avoid problems, put a period as the first character of each 
expression where a null value is possible. For example, the following line shows 
this suggested solution. 



&IF .&A = .&B &THEN &G0T0 -label 

Figure 76. Suggested &IF Coding to Avoid Problems with Null Values 

If either &A or &B is null, the comparison fails, but you do not get an error. If &A 
and &B are both 6, NetView reads the statement as .6 = .6 and the comparison is 
still true. You can use a period to test if a variable is null. For example, the com- 
parison .&1 = . is true when &1 is null. 

You cannot use this code suggestion with arithmetical operations. In this case, 
ensure that the result is not null to avoid receiving an error. 

Figure 77 shows some examples of comparisons. 



.5 = .&A 

.&1 = . 

2 + 2 NE &ANSWER 

&PARMCNT LE 5 

7 > 3 + &1 




Figure 77. Examples of Arithmetical Comparisons 
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Figure 78 shows four examples that use the &if control statement. 

MF &APPLID - KCCFA001 &THEH &USERVAR * 10 
*MF &NCCFID = KCCFA &THEN 4G0T0 -PR0C2 

ilF &1 - LU200 &THEN VARY NET,ACT,ID»&1 

&IF &SUBSTR &DATE 15- 12/25 &THEN WRITE HAPPY HOLIDAY 
Figure 78. Example Statements Using &IF Control Statement 



&GOTO Control Statement 



&goto unconditionally transfers control to another part of the command list. &goto 
lets you rerun statements or jump ahead to a statement of the command list. A 
statement label identifies the target or destination statement. When you use both 
&if and &goto, you can test for various conditions and go to different parts of the 
command list, depending on the results. Figure 79 shows the syntax of the &goto 
control statement. 



&GOTO -label 
Figure 79. &GOTO Control Statement Syntax 

-label 

identifies the target statement in this command list where processing will con- 
tinue. 

When NetView interprets the &goto statement, it searches the command list for a 
statement starting with this same label. NetView transfers control to that statement 
and continues the command list processing. The statement identified by the label 
can be before or after the &goto statement. 

You can code a variable for your label as long as the variable is replaced by a 
value before NetView processes the &goto statement. See "Labels" on page 75 
for further information about labels. 



&EXIT Control Statement 



When the command list reaches the &exit control statement, the command list 
processing ends. 

You can use &exit with &if to check the command list and exit if there is an error. 
You can use &exit with &goto to control the flow of the command list. Figure 80 
shows the syntax of the &exit control statement. 



t &EXIT number 

Figure 80. &EXIT Control Statement Syntax 
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number 

is an error return code. It can be equal to -1, 0, or any positive number up to 
2147483647. To debug potential problems in nested command lists, code a 
return code on &exit. 

The return code you set on the &exit control statement is placed in the &retcode 
control variable. The calling command list can test &retcode and take action 
based on the return code. See "Command List Information" on page 83 for more 
information about &retcode. 

You can define your own meanings for the positive numbers. If you code a nonzero 
return code on the &exit statement, and if &control err is in effect, the command 
list command that generated the nonzero return code is echoed on the screen. 

When a command list returns a -1, that command list, and all command lists in the 
nested chain, end. If you do not code a return code on &exit, or if the command list 
ends when the last line is processed and there is no &exit statement, a zero return 
code is set. 

Figure 81 is an example command list named stoptaf that uses the endsess 
command to stop all terminal access facility sessions. The command list checks 
for errors. To start the command list enter stoptaf or stoptaf all. If you forget 
what the command list does or forget what to enter, you can use stoptaf ? to get 
help. 



STOPTAF CLIST 
&CGNTRGL ERR 

* IF USER ENTERS STOPTAF ?, GO TO HELP SECTION 
&IF ,&1 EQ .? &THEN &G0T0 -HELP 

* IF NO PARAMETERS, GO TO COMMAND 
&IF .&! EQ . &THEN &G0T0 -CMD 

* IF PARAMETER IS ALL, GO TO COMMAND. ELSE PRINT ERROR MSG 
&IF .&1 NE .ALL &THEN &G0TQ -ERROR 

-CMD 

ENDSESS 0PCTL,ALL 

ENDSESS FLSCN»ALL 

&EXIT 

-ERROR 

&WRITE YOU ENTERED: STOPTAF &PARMSTR WHICH IS NOT CORRECT 

-HELP 

&BEGWRITE -END 

ENTER: STOPTAF TO STOP ALL TERMINAL ACCESS FACILITY SESSIONS 

-END 

&EXIT 4 

Figure 81. STOPTAF Command List Using &IF, &GCTO, and &EXIT 

If you enter stoptaf or stoptaf all, only the results of the two endsess commands 
are displayed. 

If you enter stoptaf flscn, the following message is displayed: 

YOU ENTERED: STOPTAF FLSCN WHICH IS NOT CORRECT 

ENTER: STOPTAF TO STOP ALL TERMINAL ACCESS FACILITY SESSIONS 
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if you enter stoptaf ?, the following message Is displayed: 
ENTER: STOPTAF TO STOP ALL TERMINAL ACCESS FACILITY SESSIONS 



&WAIT Control Statement 



Sometimes you might want a command list to wait for a specific event or message. 
You then define what event will cause the command list to resume processing with 
the &wait control statement. The command list can wait for any message with a 1- 
to 10-character message identifier. 

Note: &wait cannot be used when operating under the ppt task, or when using 
service point service (spsc) commands. See "Primary POI Task Restrictions" on 
page 17 for more information using &wait under the ppt task. For additional infor- 
mation about using &wait with spsc commands, refer to Chapter 10, "Service Point 
Command Service Commands" on page 165. 

If you use &wait in an automation task command list, be sure to specify a reason- 
able time-out value. For instructions on how to code a time-out event, see "The 
Event = -Label Pair" on page 113. 

&wait does the following in a command list: 

• It causes NetView to monitor the operator station task (ost) for specific mes- 
sages and takes action if the message arrives. For example, the command list 
issues a vtam command to activate a resource. When vtam sends the message 
saying the resource is active, the &wait initiates a specific action based on the 
successful activation of the resource. 

• it initiates a specific action if a message does not arrive in a specified period of 
time. For example, for your installation, you want to display resources if the 
activation message does not arrive within 5 minutes. 

Therefore, you can use &wait in the following applications: 

• The command list starts a session with an application program, such as ims/vs, 
or another NetView domain. The &wait causes NetView to monitor the operator 
station task for messages indicating the session is started; this satisfies the 
&wait condition. When the &wait condition is fulfilled, the command list 
resumes processing and sends the logon and other information. 

• The command list issues requests for status information from vtam, and then 
processes or reformats this information before sending it to the NetView oper- 
ator. 

&wait and &pause work differently. With &pause, the command list does not con- 
tinue until the operator enters the go command. Operands on the go command are 
used in the command list. However, because &wait causes the command list to 
wait for a specific event or events, go is only used to resume the command list if 
the event never occurs. When a command list is in a wait state, NetView ignores 
operands on the go command, reset, stack, and unstack work the same way for 
&wait and &pause. 
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Coding an &WAIT Control Statement 

There are several ways to code an await statement. This section discusses the 
basic format. "Customizing the &WAIT Statement" on page 118 discusses ways to 
customize &wait. 

When the command list gets to an &wait control statement, NetView displays the 
letter w on the upper right-hand corner of the terminal screen if the screen is 
refreshed as the result of a message being received or the enter key being 
pressed. This notifies the operator that a command list process is in a wait state. 
Wait state means the command list has halted its processing and is waiting for a 
specific message or group of messages. When the specific message arrives, the 
control variables and the parameter variables are set to their current values. 
Figure 82 shows the syntax of the await control statement. 



&WAIT ^command'] I 

event=-label [,...] 

Figure 82. &WAIT Control Statement Syntax 

* command 1 

is any command or command list that you can issue from NetView. This 
command is optional. It is usually the command from which the command list 
is waiting for messages. For example, if you want the command list to wait for 
a successful session startup, the entire bgnsess command is coded between 
single quotes. Be sure to code command list continuation characters before 
the event = -label pairs. The command is run as soon as it is reached in the 
command list. 

Note: The w signifying a wait state, if present, remains in the upper right 
corner of the screen while this initial &wait command is processed. The w tells 
the operator that NetView is still waiting for messages. If the operator enters 
go before this command or command list completes processing, the go is 
rejected with message DSI016I not in pause or wait status. When the command 
or command list is complete, the go is accepted, reset ends a command list 
that is in a wait state. If you enter the stack command, the w, if present, does 
not remain in the upper right-hand corner of the screen. 

You can code one of the NetView timer commands, at, every, or after, in the 
&wait statement. If the scheduled command is a command list, it cannot run 
until either the current command list is complete or the stack command is 
entered. 

event = -label 

is an events-label pair. You can code as many of these pairs as you want on 
an &wait statement, up to the limit of 255 characters. The event is usually a 
message for which the command list is waiting. The event can be a trigger that 
ends the wait state before the message arrives. The &wait statement causes 
NetView to scan all messages sent to the operator. If a message matches one 
of the events coded, the command list goes to the line with the specified label 
and continues processing from the labeled statement. For more information on 
the types of events that can satisfy an &wait, see "The Event = -Label Pair" on 
page 113. 

Note: While you can code several event = -label pairs, the first message, or other 
condition, that matches one of the events stops the command list from waiting for 
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more messages. You can change this if you want to process several messages 
with one &wait statement. See "Customizing the &WAIT Statement" on page 118. 

When NetView receives the message it is waiting for, the message is displayed on 
the operator terminal, as are all NetView messages. However, in this case, the 
message type is w unless the message satisfying the &wait originated from a 
command list, in which case the message type remains c. If you do not want the 
operator to see this message see "Customizing the &WAIT Statement" on 
page 118. 

NetView only checks messages that are intended for the operator screen. If you 
have coded exit routine dsiexo2A (output to the operator), the &wait control state- 
ment may not be able to match the message. For instance, if dsiexo2a deletes the 
message, &wait does not match it. Since the operator does not receive the 
message, neither does the waiting command list. Therefore, you should only wait 
for messages that are displayed on the NetView console. 

The Event = -Label Pair 

The event= -label pair on the &wait statement lets you pass control to a statement 
with a label when one of four types of events occurs. The label is a standard label 
as described in "Labels" on page 75. The label coded on the &wait statement can 
be a variable, but parameter variables should not be used. 

You can pass control to the label on an &wait statement by specifying an event— - 
label pair. The events you can use are: 

• token 

• *ERROR 

• *nn 

• *ENDWAIT. 



token 



The event occurs when NetView receives a message matching token, 
token is 1 to 10 characters that identify the first token of the message or 
messages for which the command list is waiting. Optionally, you can 
identify the domain of a message for which the command list is waiting. 
If a domain identifier is specified, it precedes the token and is sepa- 
rated from the token by a period {domainid.token). You can also use an 
asterisk (*) to indicate you are specifying a partial domain identifier or 
token. If you do not specify a domain identifier, the message for which 
the command list is waiting can be from any domain. 

Following are examples of some of the ways you can specify the mes- 
sages for which you want the command list to wait: 

domainid.token The event occurs when NetView receives any 

message whose domain identifier matches the 1- to 
5-character domainid and whose first token matches 
token. 

dom*. token The event occurs when NetView receives any 

message whose domain identifier matches the partial 
domain identifier specified by dom* and whose first 
token matches token. For example, nccf\dsi463i 
means the event occurs when a DSI463I message is 
received from any domain with an identifier that 
starts with nccf (such as nccfa or nccfb). 
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'ERROR 



'.token The event occurs when NetView receives any 

message whose first token matches token. The 
message can be from any domain. 

token The event occurs when NetView receives any 

message whose first token matches token. The 
message can be from any domain. 

tok* The event occurs when NetView receives any 

message whose first token matches the partial token 
specified by tok*. For example, dsi* means the event 
occurs when NetView receives any message whose 
first token begins with osi (such as Dsi463i or DSI386I). 

* The event occurs when NetView receives any 

message. 

Multi-line messages such as multi-line write-to-operator (mlwto) are 
treated as one message. Therefore, only the message identifier of the 
first message in a multi-line message is available to the &wait, and the 
&wait can be satisfied only by that message identifier. Use getmsize, 
getmtype, and getmline to access the other messages in a multi-line 
message. See "Working with Multi-Line Messages" on page 151, for 
more information on multi-line messages and an example of using 
&wait with multi-line messages. 

Note: When using a token event, messages not related to the 
command issued by the &wait can be matched to the event and, 
depending on the options on the &wait statement, can be suppressed. If 
the command list is suspended and the suppress option is in effect on 
the &wait statement, any messages received by the task are suppressed 
before the command list is resumed. 

This event occurs when the command specified on the &wait statement 
returns a nonzero return code. If you do not code 'error, NetView con- 
tinues to wait for the messages associated with this command even if 
the command ends with an error. If NetView is waiting for a message 
that says the command was successful, the operators running this 
command list will be delayed until someone issues go or reset. If 
*error is satisfied, the message control variables are set as follows: 



Control Variable 


Value 


&MSGID 


'ERROR 


&MSGORIGIN 


null 


&MSGSTR 


null 


&MSGCNT 






NetView issues the messages, so do not issue &msgid ('error) or 
&msgstr (null) at the designated label. 

Note: Messages associated with the command can be received before 
the command returns a non-zero return code. If such a message is 
coded on an event — -label pair, control is passed to the first statement 
whose event has occurred. For instance, if you code the name of the 
&wait command on a MSGiD = -/aoe/ pair, and you also code an 
'error = -label pair, NetView honors the msgid = -label pair first because 
that event occurs first. 
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*nn 

This event occurs after nn seconds. If no other event occurs, the &wait 
ends and control passes to the labeled statement. You can code a 
value between 1 and 32767 seconds (9 hours, 6 minutes, 7 seconds). If 
you do not code *nn and none of the events of the &wait are satisfied, 
&wait continues until the operator enters a go or reset command. 

If a nested command list contains an &wait statement with *nn event, 
the *nn of the original command list is ignored. 

*ENDWAIT 

This event occurs when the operator or a command list issues a go 
command. If you do not code *endwait =-/abe/, the go command con- 
tinues processing with the statement following the &wait command. 



Error Conditions 



If an error condition occurs, NetView should be able to go to another part of the 
command list and take appropriate action. Consider the types of errors you can 
have and plan to handle them by coding "error, *nn, and *endwait events. 

Coding Message = -Label Pairs 

The order in which you code MSGiD=-/aoe/ pairs is important. NetView scans the 
pairs in the order you code them, from left to right. 

For example, assume you code the statement in Figure 83. 



| &WAIT IST*=-ALL,IST123I=-SPECIAL 

Figure 83. Example &WAIT Command Using MSGID=-Label Pairs 

When NetView receives IST123I, it goes to the label -all, not -special. You should 
code IST1231 before isr. 

You can code as many events as required on one &wait control statement up to 255 
characters. Remember to use continuation characters if the event pairs take up 
more than one line. Code the message and domain identifiers in the order that you 
want them processed. NetView scans the list from left to right until a match is 
found. 



Ending an &WAIT 



An &wait can be ended in one of the following ways: 

• By the operator entering the go command. Processing continues with the next 
statement unless *endwait is specified on the &wait statement. If *endwait is 
specified on the &wait statement, processing continues with the statement 
marked by the label. 

• By the operator entering the reset command. The command list (and all of its 
nested command lists) ends. 



• 



By coding *error on the &wait statement. If the command specified on the 
&wait statement ends with an error, the command list continues processing at 
the statement marked with the label. If you do not code "error in this situation, 
the &wait does not end until the operator enters go or reset. 
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• By coding *nn on the &wait statement. The command list continues processing 
at the statement specified by the label if another event does not occur within nn 
seconds. 

• Upon receipt of a message matching an event= -label pair. The command list 
continues processing with the statement marked with the label. 

Using NetView Commands with &WAIT 

When a command list written in the NetView command list language is in a pause 
or wait state, operator commands that are entered can be deferred. Whether the 
commands are deferred is based on the NetView defaults, override, and cmd com- 
mands. See NetView Operation for information on these commands. 

The go, stack, unstack, and reset commands affect the processing of command 
lists in a wait state as follows: 

• go ends the wait. If *endwait is coded, processing continues with the labeled 
statement. 

• stack suspends command list processing and causes any commands that have 
been deferred to be processed. You can enter any command or command list 
for normal processing while a command list is suspended. The &wait is not 
suspended, and events are still matched as they occur. The w, if present, does 
not remain in the upper right corner of the NetView screen. The go command 
is rejected until the command list resumes processing. 

• unstack resumes command list processing. The &wait resumes processing 
events that were matched while the command list was suspended. The &wait 
does not resume after expiration of a specified time if, while the command list 
was suspended, you ran another command list that used &wait or wait with a 
time specified. 

• reset ends a command list that is in a wait state, as well as all command lists 
related to it by nesting. 

For more information on the go, stack, unstack, and reset commands, see NetView 
Operation. 

When processing mlwto messages received in response to an &wait control state- 
ment, use the getmline, getmsize, and getmtype commands. For more information 
about these commands, see "Working with Multi-Line Messages" on page 151. 

Control and Parameter Variables Used with &WAIT 

NetView sets the values of the amsgcnt, &msgid, &msgorigin, &msgstr, and &msgtyp 
control variables and the &1 - &31 parameter variables based on the receipt of a 
message coded on an &wait control statement. 

&MSGCNT 

becomes the number of elements of the text of &msgstr. 

&MSGID 

becomes the message identifier of the message received. The message identi- 
fier is the first token of the message (up to 10 characters). If the first token is 
longer than 10 characters, &msgid uses only the first 10 characters. 

&MSGORIGIN 

becomes the name of the domain where the message originated. 
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&MSGSTR 

becomes the message text exactly as it is received by NetView. &msgstr does 
not include the message identifier (the token used by the &msgid control vari- 
able). 

&MSGTYP 

becomes the system message type of the message received. 

&1 - &31 

NetView changes the values of the &1 - &31 parameter variables to reflect the 
text of the message. Each parameter variable is set to a token of the message. 
Tokens are delimited by commas, apostrophes, or blanks. &1 is set to the first 
token following the message identifier (the token used by the &msgid control 
variable). &2 is set to the next token to the right of &1, and so on up to a 
maximum of 31 variables. 

Following is an example of how the variables are set when the following message 
from domain domoi is intercepted by an &wait: 



DSI008I SPAN1- 


NOT ACTIVE 


Variable 


Value 


&MSGORIGIN 


DOM01 


&MSGID 


DSI008I 


&MSGSTR 


SPAN1 NOT ACTIVE 


&MSGCNT 


3 


&1 


SPAN1 


&2 


NOT 


&3 


ACTIVE 


&4 - &31 


NULL 



Notes: 

1. If NetView receives a multi-line message, the control variables and parameter 
variables are set according to the first line of the message. See "Working with 
Multi-Line Messages" on page 151 for information concerning working with 
multi-line messages. 

2. If &1 - &31 are given values when the command list runs, save the parameter 
variables in user variables before invoking the &wait control statement. This 
lets you use the original values after &wait changes them. 

3. After issuing an &wait control statement, save the values of the control vari- 
ables in user variables before issuing another &wait control statement. This 
lets you use the values after another &wait changes them. 

4. If you are using await contwait, be careful when using the control variable 
&msgid before the &wait has ended. If an &write or &begwrite is used to display 
&wait as the first character in the text, the output can be suppressed or cause 
the command list to loop. If the &wait suppress option is in effect, an &write or 
&begwrite, with &msgid as the first character string of the text, matches the 
MSGiD=-/abe/ operand of the active &wait. Therefore, the text of the &write or 
&begwrite is not sent to the operator's screen. If an &wait continue statement 
is encountered after a MSGiD=-/abe/ is matched, and there is no other state- 
ment to end the command list or the &wait, the command list will loop. 
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Using &WAIT in Nested Command Lists 

The command in the &wait statement can be a command list. The nested command 
list can contain an await statement too. You should be aware of the following con- 
siderations when using &wait with nested command lists: 

• Messages that arrive for the waiting command lists are queued until the nested 
command list is finished processing. 

• If you specify the same message number on &wait statements in both the 
waiting and nested command lists, the message satisfies the &wait in the 
nested command list. 

• If you specify timer events using *nn on &wait statements in both the waiting 
and nested command lists, the timer event of the waiting command list is can- 
celed. 

Customizing the &WA1T Statement 

The previous sections described the simplest form of the &wait command, where 
the first message received that satisfies the wait is displayed on the operator's ter- 
minal and causes the command list to continue processing. 

This section describes how to customize the &wait statement for even more flexi- 
bility. 

To customize your &wait statements use the following syntax. 



&WAIT fDISPLAY lSUPPRESSI 
[ENDWAHICONTWAIT ] 
[CONTINUE] 

Figure 84. Syntax for Customizing an &WAIT Statement 

PISPLAYI SUPPRESS 

determines whether a message that matches a wait event is displayed at the 
operator's terminal. The display and suppress options can be changed at any 
point in a command list. Once messages have been suppressed, you must 
code another &wait statement with the display operand to begin displaying 
messages again. 

DISPLAY indicates that the message the command list is waiting for is to 

be displayed at the operator's terminal upon arrival to 
NetView. This is the default value. 

SUPPRESS indicates that any messages that have satisfied an &wait are 
not displayed. 

Note: When suppress is in effect, you do not know whether 
messages have been received. Therefore, it is possible that 
all of the messages will not be processed when an operator 
issues a go or reset command to end an &wait. 

ENDWAIT1 CONTWA1T 

indicates whether the command list should continue to wait for additional 
events or should end the wait after the first event that satisfies the &wait. The 
endwait and contwait options can be changed at any point in a command list. 
Once contwait has started, you must code another &wait statement with the 
endwait operand to return to the default value. 

118 NetView Customization: Writing Command Lists 



NetView Command List Language Command Lists 



ENDWAIT sets up processing for the next event = -label pair to be proc- 

essed. This is the default value, endwait indicates that the 
current, or the next, event = -label pair ends after the first 
event that satisfies the &wait. Although endwait does not end a 
wait already in process, operators can still use the go 
command to end the wait. The reset command, which ends a 
wait, also ends the command list. 

CONTWAIT indicates that the next &wait event = -label statement encount- 
ered waits for additional events until the wait is ended. This 
enables one &wait statement to process more than one event. 
This is useful when you want to retrieve more than one 
message from a single command, such as a list command. 

CONTINUE 

directs the command list to continue waiting for the next event that satisfies the 
original &wait statement, continue is used only when &wait contwait is speci- 
fied prior to the &wait event— -label. If you want the wait to continue after 
event processing is finished, code &wait continue. This directs the command 
list to continue waiting for the next event that satisfies the original &wait state- 
ment. 

The operands of this format are optional and can be coded in any order. However, 
they cannot be coded on the &wait event- -label statement. The &wait statement 
does not put the command list into a wait state. Instead, it indicates how the 
command list processes the next await event = -label control statement. 

If you update this statement using suppress, contwait, or continue, the new settings 
remain in effect for the rest of the &wait statements in the command list, including 
an &wait currently in process. To reinstate the initial settings, you must code 
another &wait statement with the appropriate operands. If you activate a nested 
command list, the default settings are in effect for that command list unless an 
&wait statement is coded for the nested command list. 

Ending &WAIT if CONTWAIT is in Effect 

"Ending an &WAIT" on page 115 described ways to end a wait when a command 
list is waiting for only one event. When the command list is waiting to match more 
than one event, you can end the wait in one of the following ways: 

• By entering the go command at the terminal. 

If an &wait continue was the last &wait statement encountered, processing con- 
tinues with the next command list statement following the &wait continue state- 
ment. If the *endwait event is coded, processing continues at the label 
statement. If no event= -label match has occurred, processing continues with 
the line following the &wait statement. 

• By coding the go command in the command list statement that follows an &wait 
endwait statement. 

If the 'endwait event is coded, processing continues at the label statement. If 
no event=-label match occurred, processing continues with the line following 
the go command. 

• By coding -error as the event on the &wait statement. 

If the command specified on the &wait statement ends with an error, the 
command list continues processing at the statement specified with a label. 
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The await does not end unless an error occurs. However, if there is an error in 
the command list and you do not have *error coded, the wait may never end. 

• By coding *nn on the &wait statement. 

The command list continues processing at the statement specified with a label 
if the event does not occur within nn seconds. 

• By coding *endwait on the &wait statement. 

The command list continues processing at the statement specified with the 
label when the operator enters the go command. 

• By coding &exit following a label. 

This causes the command list to end normally. 

• By entering the reset command. 

The command list, including the command list that initiated it, ends. 

Note: Because &wait contwait queues NetView messages, you should also code 
&wait continue to receive these queued messages. If you code &wait contwait with 
suppress and end the wait, you could lose some messages. 

Suggestions for Coding &WAIT 

It is best to use the &wait [endwait|contwait] options in the following way: 

1 . Set up options for the &wait event= -label statement by coding &wait with 
contwait, suppress, or their defaults. 

2. Enter an &wait state by using an &wait event=-label statement. 

• If &wait endwait is specified before the &wait event = -label statement, or is 
in effect by default, the first matched event ends the wait, and command 
list processing continues. See "Ending an &WAIT" on page 115. 

• If &wait contwait is specified, the receipt of the first event does not end the 
&wait unless this event is specified in "Ending &WAIT if CONTWAIT is in 
Effect" on page 119. The command list goes to the label specified for the 
event and continues processing. 

To complete this section of the command list, do one of the following: 

- Continue the wait by coding &wait continue. 

- Specify that the next event is the last of this wait by coding &wait 
endwait and then &wait continue. 

- End the wait by coding the &wait endwait statement and go command 
in the command list. 

- End the command list by coding &exit. 

3. Continue the command list according to the results of step 2. 

Sample Using & WAIT 

This section contains an example of the &wait statement in a command list. 

Figure 85 on page 121 is an example illustrating the use of &wait to wait for one 
message. The command list is named actone, and it issues a vtam command to 
activate a logical unit. The command list traps the messages responding to the 
activate command, then reformats the messages and writes them to the operator's 
screen. This command list is activated by entering actone nodel 
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&C0NTR0L ERR 



* 



ACTONE COMMAND LIST 



f * THIS COMMAND LIST ISSUES A VTAM "V NET, ACT" COMMAND, TRAPS ITS 

I * MESSAGES AND REFORMATS THEM. 

I ******************* ************** 

l * • 

: * IF THERE IS NO INPUT PARAMETER, ASK FOR ONE 

&IF ,&1 = . &THEN &GOTO -BADIN 

* SAVE THE INPUT PARAMETER 
; &LU = &1 

! * END THE WAIT WITH THE FIRST MESSAGE AND DO NOT DISPLAY THE 

* INPUT MESSAGE ON THE SCREEN 
&WAIT ENDWAIT SUPPRESS 

* ISSUE WAIT WITH THE COMMAND 

&WAIT 'V NET,ACT,ID=&LU',IST093I=-REF0RM,*ERR0R=-FAIL,+ 

IST105I=-FAIL,*ENDWAIT=-GOIN 
-REFORM 

* REFORMAT MESSAGE IST093I (SUCCESSFUL) AND WRITE TO THE SCREEN 

* &1 IN THE FOLLOWING LINE IS NOT THE ORIGINAL &1 
&ACTIV = &1 

&WRITE VTAM MESSAGE IST093I WAS RECEIVED 
&WRITE &ACTIV IS NOW ACTIVE 
&GOTO -END ALL 
-FAIL 

* REFORMAT MESSAGE IST105I (UNSUCCESSFUL) AND WRITE TO THE SCREEN 
&WRITE &LU COULD NOT BE ACTIVATED 

&GOTO -ENDALL 
-GOIN 

* IF "GO" ISSUED, INDICATE THAT MESSAGES HAVE NOT BEEN RECEIVED 
&WRITE "GO" INPUT COMMAND LIST ACTONE — &LU IS NOT ACTIVE NOW 
&GOTO -ENDALL 

-BADIN 

&WRITE RE-CALL COMMAND LIST ACTONE WITH PARAMETER OF LU TO BE ACTIVATED 
\ -ENDALL 
&WRITE COMMAND LIST ACTONE COMPLETE 
&EXIT 

Figure 85. Command List Issuing &WAIT for One Message 

The actone command list waits for one of the following messages: 

IST093I modename ACTIVE 

IST105I modename NODE NOW INACTIVE 

The command list is activated by entering actone and operand nodel The operand 
is the name of the logical unit to be activated. This operand supplies the value for 
parameter variable &1. Receipt of a message indicating success (IST093I) or failure 
(1ST1051) caused the wait to end because endwait was specified. Processing con- 
tinues at the specified label (-reform for IST093I, -fail for istiosi). The awaited mes- 
sages are not displayed because suppress was specified, but any other messages 
are displayed. 
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Upon successful activation of nodei, the following message text is displayed on the 
operator's terminal: 



ACTONE NODEI 

IST897I VARY ACCEPTED 

VTAM MESSAGE IST093I WAS RECEIVED 

N0OE1 IS NOW ACTIVE 

COMMAND LIST ACTONE COMPLETE 
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Chapter 8. NetView Command List Language Global 
Variables 

This chapter describes the syntax and use of global variables that are used in 
command lists written in the NetView command list language. You will learn how 
to assign values to global variables used in command lists running under the same 
task and how to assign values to global variables that can be passed between 
command lists that are running under different tasks. 

Global variables allow values to be defined, referenced, and updated by different 
operators. Values are passed to a command list for updates, and the updated 
values are passed back to the first command list. For example, command list 
clista can assign a value to a task global variable, &vari, and then activate its 
nested command list, clistb. The nested command list, clistb, can check the value 
assigned to &vari by clista, update the value, and return control to clista. The 
original command list, clista, now has access to the value assigned to &vari by 

CLISTB. 

There are two types of global variables; task and common. Task global variables 
let you define, reference, and update any number of global variables to a particular 
task. The common global variable allows definition of user variables that can be 
referenced by command lists running under any task, as opposed to task global 
variables, which can only be referenced by a single task. 

When you create global variables, follow these rules: 

• The global variable can be 1 to 11 characters. A-Z, 0-9, #, @, and $ are valid 
characters. 

Note: If you want global variables you create in a rexx command list to also 
be accessible to command lists written in the NetView command list language, 
make sure the global variable names are from 1 to 11 characters in length and 
do not contain a period, _, 0, !, or ?. 

• If more than one global variable is specified on the globalv. 

• On the definition statement, an ampersand (&) should not be coded with the 
global variable name except where you want variable substitution performed. 
Substitution occurs for any variable with an ampersand. Whenever you use the 
global variables (except when defining them), you must append an ampersand 
to the variable name, just as you would for user variables. 

• You need two ampersands when referencing a global variable indirectly. See 
"How Parameter Variables Are Used in the Command List" on page 79 and 
"Variable Substitution Order" on page 76 for more information on indirect ref- 
erencing of variables. 

• The value of the global variable may be 255 characters long. For Kanji the 
maximum number of double-byte characters between the shift-out and shift-in 
is 126. 

• You can give global variables a numerical value between -2147483647 and 
2147483647. 
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Task Global Variables 



A task global variable can only be referenced by command lists that run under the 
same task. 

Use the following control statement as a model to define any variable as a task 
global variable. Figure 86 shows the syntax of the &tglobal control statement. 



&TGLOBAL variable [,...] ' "% 

Figure 86. &TGLOBAL Control Statement Syntax 

This statement defines the listed variables as task global variables. This means 
that, from this statement in the command list, &va/7ao/e1 refers to a task global 
variable. The value of any variable defined by this statement is whatever was most 
recently assigned to it by another command list running under the same task. If no 
value was defined, the value is null. If the atglobal statement is not used in each 
command list before a variable is referenced, that variable defaults to a local user 
variable. 

Here is an example using the &tglobal control statement. 



&NAME = JOHN 
&TGL0BAL ABC,&NAME 

Figure 87. Example &TGLOBAL Control Statement 

The first line consists of a local user variable set to the value john. The second 
line defines two task global variables as follows: 

• abc becomes task global variable &abc. The value of &abc is null because a 
value was not defined. 

• &name becomes task global variable &john. The value of &john is null because 
a value has not been defined. 

See "Scope of Variables in Command Lists" on page 127 for information on the 
interaction of task global variables with user variables and common global vari- 
ables. 

If more than one variable name is specified on the &tglobal statement, the vari- 
able names must be delimited by commas or blanks. 

The following are suggestions for using task global variables: 

• The profile ic can set task global variables to indicate a message suppression 
level or message compression that is different for different types of operators. 
Command lists driven by various messages can test these variables to deter- 
mine what information a particular operator needs. 



• 



Any command list can set up and initialize any number of parameters for 
another command list running under the same operator task. This provides 
improved nested command list communication because task global variables 
can return information from a nested command list. 
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• Task global variables can maintain accurate information about the network 
regardless of operators logging on and off. Task global variables can keep 
cumulative information from unsolicited access method messages. For 
example, notification of a failing resource can be used to recover the resource. 
With a global variable, a count of the number of retries can be maintained to 
prevent a loop. 



Updating Task Global Variables 



Figure 88 and Figure 89 are examples of command lists. The first command list is 
named clisti, and it contains the nested command list updatel These command 
lists show how to define, reference, and update a task global variable. 



* THIS STATEMENT DEFINES TOM AS A TASK GLOBAL VARIABLE. 
&TGL0BAL TOM 

! * THIS ASSIGNMENT STATEMENT GIVES THE TASK GLOBAL 
;* VARIABLE, "TOM", A VALUE OF 5. 
&T0M = 5 

* THIS STATEMENT CALLS A NESTED COMMAND LIST NAMED UPDATEl. 

* TOM IS A PARAMETER THAT IS PASSED TO COMMAND LIST UPDATEl. 
UPDATEl TOM 

* THIS STATEMENT WILL WRITE VALUE OF TOM. 
&WRITE TOM = &T0M 

&EXIT 

Figure 88. CLIST1 Command List to Define, Update, and Reference Task Global Variables 



* THIS STATEMENT OEFINES &1 AS A TASK GLOBAL VARIABLE. 
k &1 IS SET TO THE VALUE OF THE POSITIONAL PARAMETER 
k TOM, WHICH ON THE FIRST PASS IN THIS CASE IS 5. 

&TGL0BAL &1 

* THIS STATEMENT TESTS FOR A NULL VALUE AND INITIALIZES 
k THE TASK GLOBAL VARIABLE PASSED AS &1 TO A VALUE OF 

* IF THE VALUE WAS NULL. 

* THE TASK GLOBAL VARIABLE PASSED AS il IS REFERENCED 

* AS &&1. THE VALUE OF &&1 IS EQUAL TO THE VALUE OF TOM, 
k WHICH WAS PASSED TO COMMAND LIST UPDATE FROM CLISTI. 

&IF .&&1 EQ . &THEN &&1 = 

* THIS STATEMENT UPDATES THE TASK GLOBAL VARIABLE, &&1, 
k BY AN INCREMENT OF 1. 

* THIS UPDATED VALUE OF &&1 PASSED BACK TO CLISTI 
v * AS TASK VARIABLE &T0M. 

&&1 = &&1 + 1 
I MXIT 

Figure 89. UPDATE1 Command List to Update Task Global Variables 

clisti defines a task global variable, tom. The value of the task global variable tom 
is null until a value is assigned using the assignment statement, &tom = 5. clisti 
activates a nested command list named updatel 
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updatei defines a task global variable, &1. Task global variable &1 receives the 
value passed from clisti through the positional parameter tom. The NetView 
program scans variables from right to left, so the &1 part of &&1 is evaluated first, 
and the value of &1 is equal to the value of tom. The value of task global variable 
&1 is referenced as &&1. The initial value of &&1 is 5, and then &&1 is incre- 
mented by 1 using the &&1 = &&1 + 1 statement. 

The updated value is returned to task global variable atom in clisti. The &write 
tom = &tom statement displays the updated value of the &tom task global variable. 



Common Global Variables 



Use the &cglobal control statement to define any variable as a common global var- 
iable. Figure 90 shows the syntax of the &cglobal control statement. 



&CGLOBAL variable [,..,] 1 

Figure 90. &CGLOBAL Control Statement Syntax 

This statement defines the listed variables as common global variables. The value 
of any variable defined by this statement is whatever was most recently assigned 
to it by any other command list. If no value has been defined, the value is null. If 
the &cglobal statement is not used in each command list before a variable is refer- 
enced, that variable defaults to a local user variable. 

Following is an example using the &cglobal control statement. 



&NAME » JOHN 
&CGL0BAL ABC f &NAHE 

Figure 91. Example &CGLOBAL Control Statement 

The first line consists of a local user variable set to the value john. The second 
line defines two common global variables as follows: 

• abc becomes common global variable &abc. The value of &abc is null because 
a value has not been defined. 

• &name becomes common global variable &john. The value of &john is null 
because a value has not been defined. 

Note: Be careful if you have more than one command list running under different 
tasks and accessing the same global variable. The last value that the variable is 
set to is the value that is retrieved by any command list accessing the variable. 
For example, a command list accesses a common global variable and then before 
that command list updates the variable, another command list running under a dif- 
ferent task accesses the variable. If both command lists update the variable, the 
variable assumes the value given to it by the command list that updates it last. To 
avoid having a common global variable being used by different command lists at 
the same time, you can have all command lists that use the variable run under the 
same task. 
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See "Scope of Variables in Command Lists" on page 127 for information on the 
interaction of common global variables with user variables and task global vari- 
ables. 

If more than one variable name is specified on the &cglobal statement, the vari- 
able names must be delimited by commas or blanks. 

You can use the NetView-supplied command lists updcglob and setcglob to update 
and set common global variables under the ppt. See NetView Operation for infor- 
mation on using updcglob and setcglob. 



Scope of Variables in Command Lists 



If a global variable is defined with the same name as a local variable, the value of 
the local variable is lost. The global variable does not receive the value of the 
local variable. The value of the global variable is null until a value is assigned. 

If a common global variable is defined after the task global variable has been 
defined and has the same name as a task global variable, the value of the task 
global variable remains unchanged. However, the value of the task global variable 
can no longer be accessed by this command list unless the variable is redefined 
using &tglobal. 

If a task global variable is defined after the common global variable has been 
defined and has the same name as a common global variable, the value of the 
common global variable remains unchanged. The value of the common global var- 
iable, however, can no longer be accessed by this command list unless the vari- 
able is redefined using &cglobal. 

globvari and globvar2 (Figure 92 on page 128 and Figure 93 on page 130) illus- 
trate the scope of user variables, task global variables, and common global vari- 
ables within individual command lists and command lists running under different 
tasks. These two command lists give you examples of the following variable 
manipulations: 

• Assigning values to user variables 

• Defining task global variables 

• Defining common global variables 

• Setting values for common global variables 

• Changing common global to task global variables. 

In the examples, the values of the different variables are shown in parentheses. 
Notice how the values start out as nulls before values are assigned. 

The examples assume that the command lists are run under different tasks and 
that globvari is run before globvap.2. Because the command lists run under dif- 
ferent tasks, they do not access the same task global variables. Because globvari 
runs before globvar2, globvar2 accesses the values that globvari sets for 
common global variables. 
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&C0NTROL ERR 

*** MEMBER NAME GL0BVAR1 

*** ASSIGN VALUES TO SEVERAL USER VARIABLES AND PRINT THEIR VALUES 
****************************************************************** 

&NAME » JON 

&ADDR .- BAHAMA 

&PROF * REALTOR 

CLEAR 

&BEGWRITE SUB -ENOLOCAL 

FROM GLOBVAR1: AFTER LOCAL VARIABLES ASSIGNED 
VARIABLE VARIABLE VARIABLE 
TYPE NAME VALUE 



LOCAL NAME &NAME (JON) 

LOCAL ADOR &ADDR (BAHAMA) 

LOCAL PROF &PROF (REALTOR) 

-ENOLOCAL 

***DEFINE TASK GLOBAL VARIABLES 
******************************* 

&TGLOBAL NAME ADDR CALLS 
&BEGWRITE SUB -ENDTG1 

FROM GLOBVAR1: AFTER TGLOBAL VARIABLES DEFINED 
VARIABLE VARIABLE VARIABLE 
TYPE NAME VALUE 



LOCAL 


PROF 


&PROF 


(REALTOR) 


TASK 


NAME 


&NAME 


(NULL) 


TASK 


ADDR 


&ADDR 


(NULL) 


TASK 


CALLS 


&CALLS 


(NULL) 



NOTE THAT THE VALUES ASSIGNED TO NAME AND ADDR 
HAVE BEEN LOST AS THESE ARE NO LONGER LOCAL 
VARIABLES AND THE TASK GLOBAL VARIABLES HAVE NOT 
BEEN ASSIGNED A VALUE YET. 
-ENDT61 

* ASSIGN VALUES TO THE TASK GLOBAL VARIABLES 

******************************************** 

&NAME '« DOUGLAS 
&ADDR * CARY 
&CALLS = 5 
&BEGWRITE SUB -ENDTG2 

FROM GLOBVAR1: AFTER VALUES ASSIGNED TO TGLOBAL VARIABLES 
VARIABLE VARIABLE VARIABLE 

TYPE NAME VALUE 





LOCAL 


sstsssssssss 

PROF 


&PROF (REALTOR) 




TASK 


NAME 


&NAME (DOUGLAS) 




TASK 


ADDR 


&ADDR (CARY) 




TASK 


CALLS 


&CALLS (5) 


ENDTG2 









Figure 92 (Part 1 of 3). GLOBVAR1 Example Showing Scope of Global Variables 
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***DEFINE COMMON GLOBAL VARIABLES 

********************************* 

&CGL0BAL NAME ADDR NUMBER 
&BEGWRITE SUB -ENDTG3 

FROM GL0BVAR1: AFTER CGLOBAL VARIABLES DEFINED 
VARIABLE VARIABLE VARIABLE 
TYPE NAME VALUE 









LOCAL 


PROF 


&PROF (REALTOR) 


TASK 


CALLS 


&CALLS (5) 


COMMON 


NAME 


&NAME (NULL) 


COMMON 


ADDR 


&ADDR (NULL) 


COMMON 


NUMBER 


&NUMBER (NULL) 



NOTE THAT THE VALUES ASSIGNED TO TASK GLOBAL 
VARIABLES NAME AND ADDR HAVE BEEN REPLACED BY 
COMMON GLOBAL VARIABLES NAME AND ADDR. THESE 
ARE NULL AS NO VALUE HAS BEEN ASSIGNED TO THEM YET, 
-ENDTG3 

***ASSIGN VALUES TO COMMON GLOBAL VARIABLES 

******************************************** 

&NAME = WILLIAM 
&ADDR = PHOENIX 
&NUMBER = 10 
&BEGWRITE SUB -ENDTG4 

FROM GL0BVAR1: AFTER CGLOBAL VARIABLES ASSIGNED 
VARIABLE VARIABLE VARIABLE 
TYPE NAME VALUE 



LOCAL 


PROF 


&PROF (REALTOR) 


TASK 


CALLS 


&CALLS (5) 


COMMON 


NAME 


&NAME (WILLIAM) 


COMMON 


ADDR 


&ADDR (PHOENIX) 


COMMON 


NUMBER 


&NUMBER (10) 



-ENDTG4 



* CHANGE ONE COMMON GLOBAL VARIABLE BACK TO A TASK GLOBAL VARIABLE 

****************************************************************** 



&TGLOBAL NAME 
&BEGWRITE SUB -ENDTG5 

FROM GL0BVAR1: AFTER FINAL TGLOBAL STATEMENT 
VARIABLE VARIABLE VARIABLE 
TYPE NAME VALUE 



LOCAL 


PROF 


&PROF (REALTOR) 


TASK 


NAME 


&NAME (DOUGLAS) 


TASK 


CALLS 


&CALLS (5) 


COMMON 


ADDR 


&ADDR (PHOENIX) 


COMMON 


NUMBER 


&NUMBER (10) 


Figure 92 (Part 2 of 3). GL0BVAR1 Example 


Showing Scope of Global V* 
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NOTE THAT NAME NOW HAS THE VALUE OF THE TASK 
GLOBAL VARIABLE NAME AGAIN AS THE MOST RECENT 
DECLARATION STATEMENT DEFINED IT AS TASK GLOBAL. 

-ENDTG5 : 

&WRITE END OF CLIST: GL0BVAR1 
EXIT 

Figure 92 (Part 3 of 3). GLOBVAR1 Example Showing Scope of Global Variables 



&C0NTR0L ERR 

*** MEMBER NAME GL0BVAR2 

*** ASSIGN VALUES TO SEVERAL USER VARIABLES AND PRINT THEIR VALUES 
***************************************** 

&NAME - RICHARD 

&ADDR » CLAYTON 

&PROF = BARBER 

CLEAR 

&BEGWRITE SUB -ENDLOCAL 

FROM GL0BVAR2: AFTER LOCAL VARIABLES ASSIGNED 
VARIABLE VARIABLE VARIABLE 
TYPE NAME VALUE 



LOCAL NAME &NAME (RICHARD) 

LOCAL ADDR &ADDR (CLAYTON) 

LOCAL PROF &PROF (BARBER) 

-ENDLOCAL 

***DEFINE TASK GLOBAL VARIABLES 
******************************* 

&TGLOBAL NAME ADDR CALLS 

&WRITE ENTER 'GO* TO CONTINUE 

&PAUSE 

CLEAR 

&BEGWRITE SUB -ENDTGI 

FROM GL0BVAR2: AFTER TGLGBAL VARIABLES DEFINED 
VARIABLE VARIABLE VARIABLE 
TYPE NAME VALUE 



LOCAL PROF &PROF (BARBER) 
TASK NAME &NAME (NULL) 
TASK ADDR &ADDR (NULL) 
TASK CALLS &CALLS (NULL) 
NOTE THAT THE VALUES ASSIGNED TO NAME AND ADDR 
HAVE BEEN LOST AS THESE ARE NO LONGER LOCAL 
VARIABLES AND THE TASK GLOBAL VARIABLES HAVE NOT 
BEEN ASSIGNED A VALUE YET. ALSO, SINCE THIS 
COMMANO LIST RUNS UNDER A DIFFERENT TASK THAN 
GL0BVAR1, THE VALUES ASSIGNED TO THE TASK 
GLOBAL VARIABLES BY GLOBVAR1 ARE NOT REFERENCED 
HERE. . ' ..-,•.' \.. -:' • 
-ENDTGI 

Figure 93 (Part 1 of 3). GLOBVAR2 Example Showing Scope of Global Variables 



130 NetView Customization: Writing Command Lists 



NetView Command List Language Command Lists 



* ASSIGN VALUES TO THE TASK GLOBAL VARIABLES 

******************************************** 

&NAME -* DAVID 

&ADDR = RALEIGH 

&CALLS - 1 ' 

&WRITE ENTER 'GO' TO CONTINUE: 

&PAUSE 

CLEAR 

&BEGWRITE SUB -ENDTG2 

FROM GL0BVAR2: AFTER VALUES ASSIGNED TO TGLOBAL VARIABLES 
VARIABLE VARIABLE VARIABLE 
TYPE NAME VALUE 



LOCAL 


PROF 


&PROF (BARBER) 


TASK 


NAME 


&NAME (DAVID) 


TASK 


ADDR 


&ADDR (RALEIGH) 


TASK 


CALLS 


&CALLS (1) 


-ENDTG2 






***DEFINE COMMON GLOBAL VARIABLES 





********************************* 

&CGLOBAL NAME ADDR NUMBER 

&WRITE ENTER «GO' TO CONTINUE 

&PAUSE 

CLEAR 

&BEGWRITE SUB -ENDTG3 

FROM GL0BVAR2: AFTER CGLOBAL VARIABLES DEFINED 
VARIABLE VARIABLE VARIABLE 
TYPE NAME VALUE 



LOCAL 


PROF 


&PROF (BARBER) 


TASK 


CALLS 


&CALLS (1) 


COMMON 


NAME 


&NAME (WILLIAM) 


COMMON 


ADDR 


&ADDR (PHOENIX) 


COMMON 


NUMBER 


&NUMBER (10) 



NOTE THAT THE VALUES ASSIGNED TO TASK GLOBAL 
VARIABLES NAME AND ADDR HAVE BEEN REPLACED BY 
THE VALUES ASSIGNED TO COMMON GLOBAL VARIABLES 
NAME AND ADDR. IF GLOBVAR1 HAD NOT BEEN RUN 
FIRST, NAME AND ADDR WOULD BE NULL. 



-ENDT63 



Figure 93 (Part 2 of 3). GLOBVAR2 Example Showing Scope of Global Variables 
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* 

* CHANGE ONE COMMON GLOBAL VARIABLE BACK TO A TASK GLOBAL 

VARIABLE 

****************************************************** 

&TGL0BAL NAME 

&WRITE ENTER 'GO 1 TO CONTINUE 

&PAUSE 

CLEAR 

&BEGWRITE SUB -ENDTG4 

FROM GL0BVAR2: AFTER FINAL TGLOBAL STATEMENT 
VARIABLE VARIABLE VARIABLE 
TYPE NAME VALUE 



LOCAL 


PROF 


&PROF (BARBER) 


TASK 


NAME 


&NAME (DAVID) 


TASK 


CALLS 


&CALLS (1) 


COMMON 


ADDR 


&ADDR (PHOENIX) 


COMMON 


NUMBER 


&NUMBER (10) 



NOTE THAT NAME NOW HAS THE VALUE OF THE TASK 
GLOBAL VARIABLE NAME AGAIN AS THE MOST RECENT 
DECLARATION STATEMENT DEFINED IT AS TASK GLOBAL. 

-ENDTG4 

&WRITE END OF CLIST: GL0BVAR2 
&EXIT 

Figure 93 (Part 3 of 3). GLOBVAR2 Example Showing Scope of Global Variables 
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Chapter 9. Message Automation 



This chapter provides the following information about message automation for the 
NetView program: 

A definition of message automation 

How message automation for NetView Release 3 differs from nccf and NetView 
Release 1 

How to define command lists for message automation 

How to send messages from a message automation command list to the mvs 
operator console 

How to route messages from message driven command lists 

How to parse variables using the parsel2R command 

How to process multi-line messages 

How to use the sdomain command with the quiet option to return messages for 
automation processing 

How to migrate to NetView Release 3 message automation. 

This chapter is intended to help the customer perform message automation using 
command lists. It primarily contains guidance in implementing message auto- 
mation. Unless specifically stated otherwise, the information in this chapter must 
not be used for programming purposes. However, this chapter also provides 
general use programming interfaces, which are explicitly identified when they 
occur. These interfaces are provided to allow the customer to write programs that 
use the services of the NetView program. 



What Is NetView Message Automation 



NetView message automation is a process that allows you to automate system 
response to messages. This allows you to have command lists and commands that 
are issued automatically when specific messages occur during operations. To 
learn more about setting up message automation for your system, see NetView 
Installation and Administration Guide. 



How NetView Release 3 Message Automation is Different 

NetView Release 3 message automation differs from nccf and NetView Release 1. 
However, NetView Release 3 and NetView Release 2 have the same message auto- 
mation. The following sections describe the differences in NetView message auto- 
mation between Release 3 and nccf and Release 1. 

A utility program, dsicnvrt, is provided with NetView Release 3 to help you in 
migrating nccf or NetView Release 1 to Release 3 message automation. See "How 
to Set Up for Migration" on page 164 for information about migrating to NetView 
Release 3 message automation. More detailed information about migrating to 
NetView Release 3 is available in the NetView Installation and Administration 
Guide. 
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Note: You do not need to migrate your message automation from Release 2 to 
Release 3. 

How NetView Release 3 Differs From NCCF 

nccf allows vtam messages to be automated by treating the message as a 
command instead of a message. The message id is checked to see if it is defined 
as a command verb. If it is, the rest of the message is used as the operands of the 
command. To provide a command list to handle a message under nccf, you simply 
use the message id as your command list name, and create a cmdmdl statement for 
the command list name in dsicmd. 

NetView message automation in Release 3 allows the command list to be driven by 
the same message as it was under nccf, by using an if-then automation statement 
in the message automation member of dsiparm. If you are using mvs/occf for 
message automation, read "Conversion Considerations for MVS/OCCF" on 
page 164. 

How NetView Release 3 Differs from NetView Release 1 

NetView Release 3 message automation differs from NetView Release 1 in the way 
message automation is defined and in the new autotask command, which allows 
you to set up an automation task. If you are using mvs/occf for message auto- 
mation, read "Conversion Considerations for MVS/OCCF" on page 164. 

NetView Release 3 Message Automation Definition 

In NetView Release 1, you use a msgcmd statement in the message automation 
member instead of an if-then automation statement. The msgcmd statement associ- 
ated a message containing a given text string with the name of a command list. If 
NetView received a message defined by msgcmd, it would run the command list 
with the entire message as its parameter string (arg(1) or &parmstr). In NetView 
Release 3, you can use the if-then automation statement to parse the message into 
variables for the command list to use. 

NetView Release 3 Automation Task 

NetView Release 3 also provides the autotask command for creating automation 
subtasks. These function like Operator Station Tasks (osts) except that they are 
not logged on to a terminal and do not depend on an active vtam session. There- 
fore, messages can be processed under automation tasks to bring up vtam, jes2, 
JES3, and other system components automatically. New commands have been 
added to support the automation task. 



How to Define NetView Message-Driven Command Lists 

To define a message-driven command list, code an if-then automation statement in 
a message automation member of dsiparm. 

After you code the if-then automation statement in the message automation 
member, issue the automsg command using the name of that specific message 
automation member. You can enter the automsg command at a terminal, from a 
command list, or in an initialization command list at system startup. For the syntax 
of the automsg command, see NetView Operation. 

There is no need to pass the message text as a parameter string to your command 
list, as was done in nccf and NetView Release 1. Important variable information in 
the text of a message can be parsed into variables in the if portion of an if-then 
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automation statement. You can use the variables as parameters of the command 
list you call as an action in the then portion of the statement. This allows you to 
ignore certain characters of the message text (such as commas and apostrophes) 
instead of treating them as command syntax elements. For a complete definition of 
the syntax of the if-then automation statement, see NetView Administration Refer- 
ence. 



Sending Messages to the MVS Operator Console 



This section describes general-use programming interfaces, which allow the cus- 
tomer to write programs that use the services of the NetView program. This 
section ends where "Routing Messages from Command Lists" on page 142 begins. 

There are three NetView commands that can be used in message automation 
command lists to send and remove messages to and from the mvs system console. 
These commands run in an mvs environment only. The three commands are: 

WTO sends a message to the mvs operator console. 

WTOR sends a message to the mvs operator console and waits for a reply. 

DOM cancels a wto. 

When a command list is driven from a message automation table, certain rexx 
message functions or NetView command list language message control variables 
are assigned values when the command list starts. These values are based on the 
message that drives the command list. These message functions or control vari- 
ables are also assigned values when a msgread instruction is issued or an &wait 
control statement is satisfied within the command list. The values are replaced 
after each msgread or &wait. The values assigned by message automation, 
msgread, or &wait are called the system values. 

The wto and wtor commands use the values of the message functions or control 
variables as input when the commands are processed. However, before you issue 
a wto or wtor command, you have the option of changing the system values to 
your own user-assigned values. 

You cannot assign a value to a rexx function. Therefore, with rexx you must assign 
a value to a variable with the same name as the function (but without the paren- 
theses at the end). For example, a msgread instruction reads a message and that 
message assigns mcsflago a value of 10000100. If you want to change the value 
before issuing a wto command, you could use the following assignment statement 
to give a new value to the mcsflag variable: 

MCSFLAG = '01000100' 

Before processing the wto or wtor command, a rexx command list checks to see if 
any variables with the same names as the message functions have been set. If so, 
the command list uses the user-assigned values as input to the command. If not, 
the command list uses the current system values contained in the functions. 

The msgread instruction does not change the user-assigned variable values. If you 
want to go back to using the system values that msgread assigns to the functions, 
use the rexx drop instruction to drop the variables before issuing the wto or wtor 
command (for example, drop mcsflag). See REXX Reference for information on 
the drop instruction. 
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WTO 



With the NetView command list language, you can use assignment statements to 
directly change the values of the message control variables. For example, to 
change the value of &mcsflag, you could use the following assignment statement: 

&MCSFLA6 = 01000100 

When processing a wto orwTOR command, a NetView command list language 
command list uses the current values of the message control variables regardless 
of whether the value is a system value or user-assigned value. 



wto is a NetView command that allows you to send a message to the mvs operator 
console. In an automation task command list written to process an mvs wto 
message, you can use the NetView wto command as an alternative to automatic 
processing. For example, use a wto command for instances that require operator 
intervention, such as adding paper to a printer or choosing among several proc- 
essing alternatives. 

Figure 94 shows the syntax of the wto command. 

Note: The command is enclosed in single quotes to avoid substitution by rexx. 
When coding wto in command lists written in the NetView command list language, 
do not include the quotes. 



'WTO messagetexV 

Figure 94. WTO Command Syntax 

messagetext 

is the message you want to send to the system console. You can send a char- 
acter string or use a variable name set to the value of the message you want to 
send. 

For rexx command lists, character strings should be enclosed within quotes 
with the command. If you use a variable, put a blank after the command, close 
the quotes, then put the name of the variable outside the quotes. For example, 
if the message is contained in a variable named msgi, you would code: 

'WTO 'MSGI 

Incorrect usage of the wto command to display multi-line messages can cause the 
mvs operator's console to hang. 

The wto command does not provide error checking to enforce proper usage of the 
rexx variables or the NetView command list language control variables that are 
used as input to the command. 

The wto command uses the values of the following rexx variables or NetView 
command list language control variables as input: 

• AREAID, &AREAID 

Note: If the wto command is not issued for a mlwto message, (the linetype 
variable or the &linetype control variable is blank), then areaid or &areaid is not 
used or checked for a valid value. 

• DESC, &DESC 

• LINETYPE, &LINETYPE 
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• MCSFLAG, &MCSFLAG 

• MSGTYP, &MSGTYP 

• ROUTECDE, &ROUTCDE 

• SMSGID, &SMSGID 

• SYSCONID, &SYSCONID. 

The values of these variables determine how the wto command is processed. The 
variables provide the same input as the keywords on an mvs wto macro. If a 
command list does not set the variables before issuing the wto command, their 
values default to the current system values. For rexx command lists, the current 
system values are contained in the functions that correspond to the variable 
names. For example, the current system value for the rexx sysconid variable is 
contained in the sysconido function. 

For more information on the rexx variables used as input to wto, see "Message 
Processing Information" on page 53. For more information on the NetView 
command list language control variables used as input to wto, see "Message Proc- 
essing Information" on page 84. For more information on the mvs wto macro, see 
MVS System Programming Library: System Macros and Facilities, Vol. 2. 

The wto command returns values in the following rexx variables or NetView 
command list language control variables: 

• RC, &RETCODE 

• SMSGID, &SMSGID. 

The return code, rc or &retcode, indicates the processing results as follows: 

Code Meaning 

Processing successful 

8 No storage available to continue processing 

100 Invalid areaid or &areaid 

104 Invalid smsgid or &smsgid length 

108 Invalid smsgid or &smsgid value 

112 Invalid sysconid or &sysconid length 

116 Invalid sysconid or &sysconid value 

120 Internal decimal convert failure 

124 Command List dictionary update failure 

128 Null text without end specified 

132 Command is not allowed under ppt 

136 Invalid linetype or &linetype. 

A return code with a value greater than 200 indicates that the return code was 
passed from the mvs wto macro. Subtract 200 from the value of the return code. 
The new value corresponds to the return code that was passed from the mvs wto 
macro. Look up the meaning of the mvs wto macro return code in MVS System Pro- 
gramming Library: System Macros and Facilities, Vol. 2. For example, if you 
receive a return code of 208, look in the mvs documentation for the meaning of 
return code 8 from the mvs wto macro. 
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wtor is a NetView command that allows you to send a message to the mvs operator 
console and request a reply. Command lists that use the wtor command will not 
complete until an operator replies. Therefore, use wtor with care. If the command 
list is written in rexx, the operator reply is stored in the wtoreply variable, and the 
id of the system console that replied is stored in the sysconid variable. If the 
command list is written in the NetView command list language, the operator reply 
is stored in the control variable &wtoreply, and the id of the system console that 
replied is stored in &sysconid. 

Figure 95 shows the syntax of the wtor command. 

Note: The command is enclosed in single quotes to avoid substitution by rexx. 
When coding wtor in command lists written in the NetView command list language, 
do not include the quotes. 



'WTOR messagetext* | 

Figure 95. WTOR Command Syntax 

messagetext 

is the message you want to send to the system console. You can send a char- 
acter string or use a variable name set to the value of the message you want to 
send. 

For rexx command lists, character strings should be enclosed within quotes 
with the command. If you use a variable, put a blank after the command, close 
the quotes, then put the name of the variable outside the quotes. For example, 
if the message is contained in a variable named msgi, you would code: 

'WTOR 'MSGI 

The wtor command does not provide error checking to enforce proper usage of the 
rexx variables or the NetView command list language control variables that are 
used as input to the command. 

The wtor command uses the values of the following rexx variables or NetView 
command list language control variables as input: 

• DESC, &DESC 

• MCSFLAG, &MCSFLAG 

• MSGTYP, &MSGTYP 

• ROUTECDE, &ROUTCDE 

• SYSCONID, &SYSCONID. 

The values of these variables determine how the wtor command is processed. 
The variables provide the same input as the keywords on an mvs wtor macro. If a 
command list does not set the variables before issuing the wtor command, their 
values default to the current system values. For rexx command lists, the current 
system values are contained in the functions that correspond to the variable 
names. For example, the current system value for the rexx sysconid variable is 
contained in the sysconido function. 

If the command list is invoked from a message automation table, the current 
system values are set according to the message that activated the command list. 
Also, the current system values are reset according to messages that are proc- 
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essed within the command list by msgread for rexx command lists or &wait for 
command lists written in the NetView command list language. 

For more information on the rexx variables used as input to wtor, see "Message 
Processing Information" on page 53. For more information on the NetView 
command list language control variables used as input to wtor, see "Message 
Processing Information" on page 84. For more information on the mvs wtor macro, 
see MVS System Programming Library: System Macros and Facilities, Vol. 2. 

The wtor command returns values in the following rexx variables or NetView 
command list language control variables: 

• RC.&RETCODE 

• SYSCONID, &SYSCONID 

• WTOREPLY, &WTOREPLY. 

The return code, rc or &retcode, indicates the processing results as follows: 

Code Meaning 

Processing successful 

100 Null message text or running under ppt 

104 sysconid or &SYSCONID more than 10 digits 

108 sysconid or &sysconid not numeric 

112 Task posted to terminate 

116 wtoreply or &wtoreply command list dictionary update failure. 



dom is used in an automation task command list to remove a wto message from 
the operator console. You can use dom to remove action messages after checking 
to see that the action was taken, dom uses the smsgid variable in rexx command 
lists or the &smsgid control variable in NetView command list language command 
lists to determine which message to remove. If you do not assign a value to smsgid 
or &smsgid, the current system value is used. The wto command resets the value 
of smsgid or &smsgid each time the command issues a message. For rexx, if the 
smgsid variable is not set, wto uses the value contained in the smsgidq function. 
See "Message Processing Information" on page 53 for more information about 
smsgid or see "Message Processing Information" on page 84 for more information 

abOUt &SMSGID. 

Figure 96 shows the syntax of the dom command. 

Note: The command is enclosed in single quotes to avoid substitution by rexx. 
When coding dom in command lists written in the NetView command list language, 
do not include the quotes. 



DOM' 

Figure 96. DOM Command Syntax 

The dom command does not provide error checking to enforce proper usage of the 
rexx variables or the NetView command list language control variables that are 
used as input to the command. 
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The return code, rc or &retcode, indicates the processing results as follows: 

Code Meaning 

Processing successful 

4 Syntax error 

8 No storage available to continue processing 

100 smsgid or &smsgid had too many numerics 

104 smsgid or &smsgid was not numeric 

108 Not invoked from a command list. 



Routing Messages from Command Lists 



This section describes general-use programming interfaces, which allow the cus- 
tomer to write programs that use tNe services of the NetView program. This 
section ends where "Parsing Variables with PARSEL2R" on page 144 begins. 

In message driven command lists, use the msgroute command to route the 
message driving the command list to operators or groups of operators. Use 
msgroute when the decision where to route the message cannot be made in the 
message automation table. For example, use msgroute if you need to check the 
value of global variables or the message text of a line other than the first line in a 
multi-line write-to-operator message, before you decide where to route the 
message. 

When msgroute routes a message, message automation does not process the 
message a second time. 

Figure 97 shows the syntax of the msgroute command. 

Note: The command is enclosed in single quotes to avoid substitution by rexx. If 
you want to use variables for any parts of the command, leave the variable name 
outside of the quotes. When coding msgroute in command lists written in the 
NetView command list language, do not include the quotes. 



MSGROUTE oper [,...]: 

[acf/on-name(Y|N)] ' 

Figure 97. MSGROUTE Command Syntax 

oper[,...] 

the operator identifier of the operators to whom the message is routed. The 
operator identifier must be defined to NetView with an operator definition 
statement. See NetView Administration Reference for information on the oper- 
ator definition statement. The maximum length of an operator identifier is 8 
characters. You can code as many operator identifiers as needed. 

You can also specify group identifiers for the groups of operators to whom the 
message is routed. The group identifier must be defined to NetView with the 
assign command. See NetView Operation for information about the assign 
command. The maximum length of a group identifier is 8 characters, and it 
must begin with a plus (+) sign. 
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action-name(Y\N) 

the actions NetView should take when routing the message. Any or all of the 
following action-names can be specified: 

BEEP 

determines whether an audible alarm is sounded when the 
message is displayed. If beep is not specified, the default is beep(n). 

determines whether the message is displayed. If display is not 
specified, the default is display(Y). 

determines whether the message is placed in the hard-copy log. If 
hcylog is not specified, the default is hcylog(Y). 

determines whether the message is held on the operator's screen 
after it is displayed. If hold is not specified, the default is hold(N). 

NETLOG(N)|(Y [indicator-number] [*] \_oper\_,...^ [+girp [,...]]) 

determines whether the message is placed in the NetView log and 
whether the message activates a status monitor important message 
indicator for specified operators or groups of operators. If netlog is 
not specified, the default is netlog(Y). 

indicator-number identifies the status monitor important 
message indicator. 

* means the message is logged as important 

for the operator task that the message is 
routed to, or the current operator task (the 
task where the message is intercepted for 
automation checking). 

operl,...'] the operator identifier of the operators for 

whom the message is logged as important. 
The operator identifier must be defined to 
NetView with an operator definition state- 
ment (see NetView Administration 
Reference). The maximum length of an oper- 
ator identifier is 8 characters. You can code 
as many operator identifiers as needed. 

+gfrp[,...] the group identifier of the groups of opera- 

tors for whom the message is logged as 
important. The maximum length of a group 
identifier is 8 characters, and it must begin 
with a plus (+) sign. Define group identifiers 
with the assign command. See NetView 
Operation for more information about the 
assign command. 

If the operator is not in status monitor or log browse but is logged 
on, message CNM0391 is displayed: 

CNMG39I AN IMPORTANT MESSAGE HAS BEEN LOGGED - 
PLEASE BROWSE THE NETVIEW LOG. 
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If only an indicator-number is specified, the message is logged as 
important for the authorized receiver. The following example 
shows how netlog is coded with only an indicator-number: 

MSGROUTE 0PER1 NETL0G(Y 2) 

The message is routed to operl The message is also placed in the 
NetView log and is logged as an important message with a status 
monitor important message indicator number of 2. 

If an indicator-number and a list of operators or groups of operators 
are specified, the message is logged as important for the operators 
and groups of operators listed. The following example shows how 
a message is logged when an indicator-number and a list of opera- 
tors and groups of operators are specified: 

MSGROUTE 0PER4 NETLOG (Y 2 * 0PER1 +GRP5 0PER6) 

The message is routed to OPER4. The message is also placed in the 
NetView log and is defined as an important message with a status 
monitor important message indicator number of 2. The message 
activates a status monitor important message indicator for operl 
OPER6, all of the operators assigned to group +grps, and the current 
operator. If operators operi and OPER6 are also assigned to group 
+GRP5, each operator receives only one copy of message CNM039I (if 
they are not in statmon). 

determines whether the message is placed in the system log. If 
syslog is not specified, the default value is syslog(N). 



The return code, rc or &retcode, indicates the processing results, as follows: 

Code Meaning 

8 Operator or group identifier not specified or greater than 8 characters 

12 Invalid value for message action 

16 msgroute not entered from a rexx or NetView command list language 

command list 
20 msgroute not issued from a message driven rexx or NetView command list 

language command list, or from the message automation table 
24 Operator or group identifier or message action not in operator's scope 
28 Storage request failed 
32 dsimqs failed to route message. 



Parsing Variables with PARSEL2R 



This section describes general-use programming interfaces, which allow the cus- 
tomer to write programs that use the services of the NetView program. This 
section ends where "Working with Multi-Line Messages" on page 151 begins. 

The parsel2R command allows you to extract data from the character-string value 
of a variable and assign the extracted data to one or more variables using a set of 
rules called a "parsing template". To parse variables with the NetView command 
list language, you must use the parsel2R command. However, in rexx you can use 
either parsel2R or the rexx parse instruction. See REXX Reference for more infor- 
mation on the parse instruction. 

Figure 98 on page 145 shows the syntax of the parsel2R command. 
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Note: The command is enclosed in single quotes to avoid substitution by rexx. 
When coding parsel2R in command lists written in the NetView command list lan- 
guage, do not include the quotes. 



; 'PARSEL2R sourcevariable parsingtemplate* 

Figure 98. PARSEL2R Command Syntax 

sourcevariable 

identifies a command list variable. In rexx command lists, sourcevariable 
must be coded within the quotes. In command lists written in the NetView 
command list language, sourcevariable must be coded without an ampersand. 
parsel2R extracts data from the value of the variable you named as the 
sourcevariable. 

parsingtemplate 

is a list of symbols, patterns, or character selectors, or a combination of any of 
these, separated by blanks. parsel2R uses this list as a template when parsing 
the source variable. 

Symbols are command list variable names. In rexx command lists, code 
command list variable names inside the single quotes. In command lists 
written in the NetView command list language, code command list variable 
names without an ampersand. For more information on using symbols, see 
"Using Symbols in a Parsing Template" on page 146. 

Patterns are coded using slashes (/) as delimiters. A pattern is the part of the 
source variable that you want to match. For more information on using pat- 
terns, see "Using Patterns in a Parsing Template" on page 147. 

A character selector is coded using an asterisk (*) for each single character 
you want to extract from the source variable. For more information on using 
character selectors, see "Using Character Selectors in a Parsing Template" on 
page 150. 

parsel2R sets the return code (rc or &retcode) to indicate the processing results as 
follows: 

Code Meaning 

Processing successful 

8 No storage available to continue processing 

100 Not enough parameters 

104 Blank input buffer 

108 Command list dictionary lookup of source variable failure 

112 Invalid hexadecimal data in template 

116 Command list dictionary update failure 

120 Trailing slash (/) missing. 

For examples of how parsel2R can be used with multi-line write-to-operator 
(mlwto) messages, see "Examples of Command Lists Processing MLWTO 
Messages" on page 156. 

The following sections describe how to use symbols, patterns, and character selec- 
tors in a parsing template. 
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Using Symbols in a Parsing Template 

The symbols in the parsing template identify command list variables. In rexx 
command lists, code command list variables within the quotes that enclose 
parsel2R. In command lists written in the NetView command list language, code 
command list variables without the ampersand. If only symbols appear in the 
parsing template, the source variable data is assigned token-by-token from left to 
right. Tokens are defined as a string of non-blank characters. Tokens in the 
source variable are separated from each other by one or more blanks. The tokens 
are assigned to the command list variables you identified with symbols in the 
parsing template. 

Figure 99 shows three lines from a rexx message automation command list that 
uses a parsing template containing only symbols. Figure 100 shows the NetView 
command list language equivalent. 



TITLE = 'D0N"T TREAD (ROUGHLY) ON ME, PLEASE' 
'PARSEL2R TITLE Al A2 A3 A4 A5 A6 A7' 
'PARSEL2R TITLE Bl B2 B3' 

Figure 99. REXX PARSEL2R Example Using Symbols 



&TITLE = 'DON'T TREAD (ROUGHLY) ON ME, PLEASE' 

PARSEL2R TITLE Al A2 A3 A4 A5 A6 A7 * 

PARSEL2R TITLE Bl B2 B3 

Figure 100. NetView Command List Language PARSEL2R Example Using Symbols 

The resulting values of the variables show how the token-by-token assignment 
from left to right works. The following table shows the resulting values for the rexx 
and NetView command list language variables: 



REXX 


NetView 




Variable 


Variable 


Value 


A1 


&A1 


DON'T 


A2 


&A2 


TREAD(ROUGHLY) 


A3 


&A3 


ON 


A4 


&A4 


ME, 


A5 


&A5 


PLEASE 


A6 


&A6 


null 


A7 


&A7 


null 


B1 


&B1 


DON'T 


B2 


&B2 


TREAD(ROUGHLY) 


B3 


&B3 


ON ME, PLEASE 



Note: The value of B3 or &B3 is not a single token, but the remainder of the source 
variable after the parsel2r parsed it into the first two symbols. 

Except for the last variable, leading blanks and trailing blanks are removed from 
each token in the string before it is assigned to a variable. Variable B3 or &B3 
would have leading or trailing blanks, if title contained extra blanks before on or 
after please. 
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Using Patterns in a Parsing Template 

A pattern is a character or string of characters expected to appear within the 
source variable. It is coded in the parsel2R parsing template using slashes (/) as 
delimiters. Patterns are used within a parsing template to divide the source vari- 
able into segments. 

When a pattern that you coded in the parsing template occurs in the source vari- 
able, the preceding portion of the source variable is treated as a segment. The 
symbols you defined in the parsing template preceding the pattern are used to 
parse the tokens in the corresponding segment of the source variable. 

Note: If you want to use a slash as a part of a pattern, code two consecutive 
slashes within the delimiter slashes. parsel2R reads this as one slash to be 
matched in the source variable. Two consecutive slashes by themselves (outside 
of delimiters) means to end the parse. 

Figure 101 shows how a parsing template containing patterns and symbols can be 
used in a rexx message automation command list. Figure 102 shows the NetView 
command list language equivalent. 



PARSIT = 'D0N"T TREAD (ROUGHLY) ON ME, PLEASE' 

'PARSEL2R PARSIT Al A2 A3 /(/ Bl B2 B3 /)/ CI C2 C3 /,/ 01 02 D3' 

Figure 101. REXX PARSEL2R Example Using Patterns and Symbols 



&PARSIT = 'DON'T TREAD (ROUGHLY) ON ME, PLEASE' 

PARSEL2R PARSIT Al A2 A3 /(/ Bl B2 B3 /)/ CI C2 C3 /,/ 01 D2 03 

Figure 102. NetView Command List Language PARSEL2R Example Using Patterns and 
Symbols 

The following table shows the resulting values for the rexx and NetView command 
list language variables: 



REXX 


NetView 




Variable 


Variable 


Value 


A1 


&A1 


DON'T 


A2 


&A2 


TREAD 


A3 


&A3 


null 


B1 


&B1 


ROUGHLY 


B2 


&B2 


null 


B3 


&B3 


null 


C1 


&C1 


ON 


C2 


&C2 


ME 


C3 


&C3 


null 


D1 


&D1 


PLEASE 


D2 


&D2 


null 


D3 


&D3 


null 



Figure 103 on page 148 is another example of a parsing template containing pat- 
terns and symbols. Figure 104 on page 148 is the NetView command list language 
equivalent. 
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PARSIT = «D0K ,, T TREAD ROUGHLY, ON ME' 
'PARSEL2R PARSIT Al A2 A3 /»/ A4' 

Figure 103. REXX PARSEL2R Example Using Leading Blanks 



&PARS IT » 'DON'T TREAD ROUGHLY, ON ME • 
PARSEL2R PARSIT Al A2 A3 /,/ A4 

Figure 104. NetView Command List Language PARSEL2R Example Using Leading Blanks 

The following table shows the resulting values for the rexx and NetView command 
list language variables: 



REXX 


NetView 




Variable 


Variable 


Value 


A1 


&A1 


DON'T 


A2 


&A2 


TREAD 


A3 


&A3 


ROUGHLY 


A4 


&A4 


ON ME 



Note that because the variable right before a pattern (A3 or &A3 in the previous 
examples) is treated as the last variable in a segment, the leading and trailing 
blanks are not removed. 

If the parsing template were specified as: 

PARSEL2R PARSIT Al A2 A3 AX /,/ A4 

then the blanks would be removed from the A3 or &A3 variable, and the ax or &ax 
variable would be null. 

You can use variables as part of a pattern (between the slashes). When a variable 
is part of a pattern, it needs to be coded outside of the quotes in a rexx command 
list or with an ampersand in command lists written in the NetView command list 
language. 

Figure 105 shows three lines from a rexx command list that uses a parsing tem- 
plate with a pattern containing a variable. Figure 106 on page 149 shows the 
NetView command list language equivalent. 



A0 = ROUGHLY 

PARSIT » 'DON 1 'T TREAD (ROUGHLY) ON ME 1 

'PARSEL2R PARSIT Al A2 /('A0')/ Bl' 

Figure 105. REXX PARSEL2R Example Using a Pattern that Contains a Variable 
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' &A0 = ROUGHLY 

&PARSIT = DON'T TREAD (ROUGHLY) ON ME 
: PARSEL2R PARS IT Al A2 /(&A0)/ Bl 

Figure 106. NetView Command List Language PARSEL2R Example Using a Pattern that 
Contains a Variable 

The following table shows the resulting values for the rexx and NetView command 
list language variables: 

REXX NetView 

Variable Variable Value 



A1 &A1 DON'T 

A2 &A2 TREAD 

B1 &B1 ON ME 



In the rexx example, because ao is outside the the quotes, its value is used as part 
of the pattern. The pattern becomes (roughly). Likewise in the NetView command 
list language example, because &ao is outside the quotes, its value is used as part 
of the pattern. The pattern becomes (roughly). 

You can also use hexadecimal codes in the parsing template pattern. Code a 
hexadecimal pattern using an x before the slashes. parsel2R matches the 
hexadecimal code in the template with the character in the source variable that 
corresponds to your system. 

Figure 107 shows how to code a parsing template, containing a hexadecimal 
pattern, in a rexx command list. Figure 108 shows the NetView command list lan- 
guage equivalent. 



'PARSEL2R PARSIT Al A2 X/5B/ A3' 
Figure 107. REXX PARSEL2R Example Using a Hexadecimal Pattern 



PARSEL2R PARSIT Al A2 X/5B/ A3 

Figure 108. NetView Command List Language PARSEL2R Example Using a Hexadecimal 
Pattern 

Using patterns and symbols in a parsing template gives you a powerful tool to use 
when coding your command lists. For example, you can use parsel2r to code a 
source variable in your command list that contains a small table. You can also use 
the combination of symbols and patterns to search the source variable and assign 
a token to a variable, based on the matching pattern. This table can contain a 
string of alternating variables and labels. You can then use parsel2R to match a 
variable with a label to define the flow of logic within your command list. 
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Using Character Selectors in a Parsing Template 

Character selectors in a parsel2R are coded as one or more asterisks (*), indicating 
that the preceding symbol must be assigned one or more characters from the 
source variable. If a character selector does not follow a symbol in the template 
(that is, it is coded at the beginning of the template or following a pattern), parsel2R 
skips that number of characters. 

For example, if the source variable is: 

DSI039I MSG FROM CNM01PPT: COMMON GLOBAL VARIABLES HAVE BEEN SET 

and the parsing template is: 

/FROM / DOMNAM ***** TASK /:/ 

then the following values are assigned: 

DOMNAM or &D0MNAM = CNM01 
TASK or &TASK = PPT 

Character selectors are usually used to break up a single token into multiple vari- 
ables. 

Figure 109 and Figure 110 show a parsing template using character selectors to 
change the value of a rexx message variable or a NetView command list language 
control variable. When the command list is entered, mcsflag or &mcsflag is set to 
00000110. The command list statements set bit 6 to 0. 



•PARSEL2R MCSFLAG BITS1J ***** BIT6 * BITS7 8 **' 
BIT6 = 8 



MCSFLAG - BITS1 5 
MCSFLAG = MCSFLAG 



BIT6 
BITS7 8 



Figure 109. REXX PARSEL2R Example Using Character Selectors 



PARSEL2R MCSFLAG BITS1 5 ***** BIT6 * BITS7 8 ** 

&BIT6 =9 ~ " I 

&MCSFLAG = &C0NCAT &BITS1 5 &BIT6 1 

&MCSFLAG = &C0NCAT &MCSFLAG &BITS7J5 ^ 

Figure 110. NetView Command List Language PARSEL2R Example Using Character 
Selectors 

After executing the command list statements in the previous examples, the value of 

MCSFLAG Or &MCSFLAG JS 00000010. 
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Working with Multi-Line Messages 



This section describes general-use programming interfaces, which allow the cus- 
tomer to write programs that use the services of the NetView program. This 
section ends where "Using the SDOMAIN Command with the QUIET Option" on 
page 158 begins. 

Some commands return a reply that appears to be a sequence of separate mes- 
sages, when in fact the reply is a single multi-line write-to-operator (mlwto) 
message. NetView treats a mlwto message as a single message. Only the first 
message identifier that appears as part of a mlwto message is made available to 
satisfy a rexxtrap instruction, or a NetView command list language &wait 
command. The first line of a multi-line message is also the only line used for com- 
parisons in message automation tables. 

Figure 111 shows a mlwto message as it would appear on a NetView operator's 
screen. The message is in response to a list key=pfi command. The mlwto 
message appears to be a sequence of several separate messages, but the single 
quote that appears as the message type identifier, identifies the message as a 
single mlwto message from NetView. A double quote identifies a multi-line 
message from an ibm product other than NetView. An equal sign identifies a 
user-written multi-line message. 



NCCF NETVIEW NCF01 0PER1 81/21/88 11:15:23 

* NCF01 LIST KEY-PF1 

• NCF01 

0SI606I DISPLAY OF PF/PA KEY SETTINGS 

DSI607I KEY TYPE COMMAND 

0SI608I PF1 IMMED. APPEND PFHELP 
DSI609I END OF PF/PA KEY DISPLAY 

Figure 111. Example Multi-Line Message 

trap, &wait, and message automation table processing use only the first line of a 
multi-line message. However, NetView provides three commands that allow you to 
work with multi-line messages in a command list. These commands allow you to 
work with information in each individual line of a multi-line message. The three 
commands are: 

GETMSIZE determines the number of lines of a multi-line message. 

GETMTYPE determines the line type of a specific line in a multi-line message. 

GETMLINE assigns the text of a specific line of a multi-line message to a specified 
variable. 
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GETMSIZE 



getmsize is a command used in command lists to determine the number of lines in 
a multi-line message. Use this command in a command list that was driven by 
message automation or that has processed a message using msgread (rexx) or 
&wait (NetView command list language). 

Figure 1 12 shows the syntax of the getmsize command. 

Note: The command is enclosed in single quotes to avoid substitution by rexx. 
When coding getmsize in command lists written in the NetView command list lan- 
guage, do not include the quotes. 



'GETMSIZE variablename* 

Figure 112. GETMSIZE Command Syntax 

variablename 

identifies a command list variable coded in this command, if the command list 
is written in the NetView command list language, the ampersand should be 
removed from the variable name, getmsize sets the value of the variable to the 
number of lines in the multi-line message. If the message is a single-line 
instead of a multi-line message, the variable value is set to 1. 

getmsize sets the return code (rc or &retcode) to indicate the processing results, 
as follows: 

Code Meaning 

Successful completion, variable has been set 

8 No storage available to continue processing 

100 No variable was specified 

104 Error in multi-line message 

108 An invalid variable name was given. 

For example, assume the following statement is coded in an automation command 
list: 

GETMSIZE NUMLINES 

If the command list containing this command is triggered by the message in 
Figure 113, the variable &numlines is set to the value of 7. 



IEE104I 13.02.15 87.189 ACTIVITY 607 



JOBS 


M/S 


TS USERS 


00000 


00007 


00000 


LLA 


LLA 


LU NSW 


SYSL06 


621 


IEFPROC OWT 


TSO 


TSO 


TCAS OWT 


NETV2 


NETV2 


NETVIEW NWS 



SYSAS INITS ACTIVE/MAX VTAM 

00008 00001 00000/00300 

S JES2JES2 IEFPROC NSW S 

S BASENET BASENET VTAM NSW S 

S NETVREL2 NETVREL2 NETVIEW NSW S 
S 



Figure 113. IEE104I Message to Trigger an Automation Task Command List 

See "Examples of Command Lists Processing MLWTO Messages" on page 156 for 
examples of command lists that show how getmsize is used with mlwto messages. 
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getmtype is a command used in command lists to determine the line type of an 
individual line in a multi-line message. Use this command in a command list that 
was driven by message automation or that has processed a message using 
msgread (rexx) or &WAU (NetView command list language). 

Figure 114 shows the syntax of the getmtype command. 

Note: The command is enclosed in single quotes to avoid substitution by rexx. 
When coding getmtype in command lists written in the NetView command list lan- 
guage, do not include the quotes. 



•GETMTYPE variablename number* 

Figure 114. GETMTYPE Command Syntax 

variablename 

identifies a command list variable coded in this command. If the command list 
is written in the NetView command list language, the ampersand should be 
removed from the variable name, getmtype sets the value of this variable as 
one of the following line types: 

blank The message is a single-line message. 

C The line is a control line. 

L The line is a label line. 

D The line is a data line. 

DE The line is a data end line. 

E The line is an end line without data. 

number 

specifies the number of the line in the multi-line message for which you want 
line type information. For single-line messages, the value of number must be 
1. 

When coding an actual number for number in rexx command lists, the number 
should be inside the quotes that enclose getmtype. For example: 

'GETMTYPE TYPE1 3' 

When coding a variable for number in rexx command lists, leave a blank after 
variablename and close the quotes. Code the name of the variable that con- 
tains the value for number outside the quotes. For example, if the value of 
number is contained in a variable named numi, you would code: 

'GETMTYPE TYPE1 'NUMI 

getmtype also sets the return code (rc or &retcode) to indicate the processing 
results, as follows: 

Code Meaning 

Processing successful 

8 No storage available to continue processing 

100 Either variablename or number was omitted 

104 number has too many digits 

108 number is not a numeric value 

112 number does not equal 1 for a single-line message 

116 Requested line number does not exist 

120 Internal command list processing error 
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124 Internal command list processing error 
128 variablename invalid. 

For example, you can use getmtype along with getmsize in a command list to test 
each line of a multi-line message for the type. If you use a variable name for the 
number field in the getmtype command, you can test each line. Using getmsize, 
you can code your command list to test the correct number of lines for each 
message it receives. If the command list received the message illustrated in 
Figure 113 on page 152: 

• the line type of the first line would equal C 

• the line type of the second and third lines would equal L 

• the line type of the fourth through the sixth line would equal D 

• the line type of the seventh line would equal DE. 



getmline is used within a command list to assign the text of an individual line of a 
multi-line message to a specified variable. Use this command in a command list 
that was driven by message automation or that has processed a message using 
msgread (rexx) or &wait (NetView command list language). 

Figure 115 shows the syntax of the getmline command. 

Note: The command is enclosed in single quotes to avoid substitution by rexx. 
When coding getmtype in command lists written in the NetView command list lan- 
guage, do not include the quotes. 



'GETMLINE variablename number* f 

Figure 115. GETMLINE Command Syntax 

variablename 

identifies a command list variable coded in this command. If the command list 
is written in the NetView command list language, the ampersand should be 
removed from the variable name, getmline assigns the value of the line you 
specify to this variable name. 

number 

identifies the number of the line in the multi-line message from which you want 
to obtain the value. 

When coding an actual number for number in rexx command lists, the number 
should be inside the quotes that enclose getmline. For example: 

'GETMLINE LINE1 2' 

When coding a variable for number in rexx command lists, leave a blank after 
variablename and close the quotes. Code the name of the variable that con- 
tains the value for number outside the quotes. For example, if the value of 
number is contained in a variable named numi, you would code: 

'GETMLINE LINE1 'NUMI 
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getmline also sets the return code (rc or &retcode) to indicate the processing 
results, as follows: 

Code Meaning 

Processing successful 

8 No storage available to continue processing 

100 Either variablename or number was omitted 

104 number has too many digits 

108 number is not a numeric value 

112 number does not equal 1 for a single-line message 

116 Requested line number does not exist 

120 Internal command list processing error 

124 Internal command list processing error 

128 variablename invalid. 

For example, an automation task command list written in the NetView command 
list language contains the following two lines: 

&NUM = 2 

GETMLINE SECOND &NUM 

These two lines in a command list place the text of the second line of a multi-line 
message into the command list variable &second. 

See "Examples of Command Lists Processing MLWTO Messages" on page 156 for 
example command lists that show how getmline can be used with mlwto mes- 
sages. 
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Examples of Command Lists Processing MLWTO Messages 

The command lists in Figure 116 and Figure 117 on page 157 are examples of 
how you can code your command list to process based on the information in the 
individual lines of a multi-line message. Figure 116 is written in rexx. Figure 117 
is written in the NetView command list language. 



/* SESSCNT COMMAND LIST */ 

/* - — V 

/* FUNCTION: This command list counts the number of OPCTCL */ 
/* sessions and FLSCN sessions that are active. */ 

/* */ 

/* INPUT PARMS: None */ 

/* V 

/* OUTPUT: Two informational messages that display the number of */ 
/* OPCTCL and FLSCN sessions to the operator. */ 

OPCTLCNT = /* init OPCTL counter */ 

FLSCNCNT = /* init FLSCN counter */ 

•TRAP AND SUPPRESS MESSAGES *• /* TRAP the MLWTO msg */ 

'LISTSESS' /* issue the command */ 

'WAIT 5 SECONDS FOR MESSAGES' /* WAIT for the msg */ 

SELECT /* SELECT an EVENT */ 

WHEN EVENTQ = 'M' THEN /* message received */ 

DO /* process the message */ 

'MSGREAD' /* read the message in */ 

'GETMSIZE ' NUMLINES /* get number of lines */ 

DO CNTR = 4 TO NUMLINES /* loop thru MLWTO buf */ 

•GETMLINE LINE' CNTR /* get a line in buf */ 

/* parse the line out */ 

'PARSEL2R LINE APPLNM SRCLUNM SESSNM TYPE RESTLINE' 

IF TYPE = 'OPCTL' THEN /* OPCTL session ? */ 

OPCTLCNT = OPCTLCNT +1 /* yes, increment count */ 

ELSE /* must be FLSCN sess */ 

FLSCNCNT = FLSCNCNT +1 /* increment count */ 

'TRAP NO MESSAGES' /* end message trapping*/ 

•FLUSHQ MESSAGES' /* flush message queue */ 

END /* loop thru MLWTO buf */ 

END /* process the message */ 

OTHERWISE /* event not a message */ 

SAY 'ERROR PROCESSING LISTSESS COMMAND' /* issue an error msg */ 

END /* SELECT an EVENT */ 

/* issue messages to operator with count of FLSCN & OPCTL sessions */ 

SAY 'YOU HAVE ' OPCTLCNT ' OPCTL SESSIONS ACTIVE AND' 

SAY • • FLSCNCNT • FLSCN SESSIONS ACTIVE' 

Figure 116. Command List Using Multi-Line Messages - REXX Example 
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r &C0NTR0L ERR 

< ********************************* 

|, * 

^ * COMMAND LIST AUTHTOTE 

$ * ' 

j * THIS COMMAND LIST DISPLAYS A COUNT OF HOW MANY MESSAGES (OR GROUPS 

>' * 

|; * OF MESSAGES, USING THE * SUFFIX) HAVE BEEN ASSIGNED TO BE 

; * 

* ROUTED TO SPECIFIC AUTHORIZED RECEIVERS. 
r * 

I * IT IS CALLED AS FOLLOWS: AUTHTOTE 

r * 

; * AUTHTOTE DISPLAY 

i * AUTHTOTE SUPPRESS 

I * THE FIRST TWO FORMS WILL DISPLAY THE MESSAGES RECEIVED ("DISPLAY" 

I * IS THE DEFAULT) AND A COUNT OF THE TOTAL NUMBER OF ASSIGNMENTS 

* MADE, AND THE LAST FORM WILL SIMPLY DISPLAY THE TOTAL NUMBER 

* OF ASSIGNMENTS. 

;. * 

********************************* 
* * 

* SAVE THE INPUT PARAMETER 
: &OPT = &1 

\ * INITIALIZE THE COUNTER FOR THE NUMBER OF MESSAGES ASSIGNED TO 

* AUTHORIZED RECEIVERS. 
&COUNT « 

* SET THE COUNTER FOR THE NUMBER OF THE MESSAGE LINE TO BE 

* PROCESSED TO 1. THE WAIT STATEMENT PROCESSES THE FIRST MESSAGE LINE. 
&MSZI =0 

* ISSUE THE COMMAND AND ENTER WAIT STATE 
&WAIT ENDWAIT &OPT 

&WAIT 'LIST MSG=AUTH\DSI636I=-C0UNTER,0SI643I=-N0EXIT, + 

*60=-TIME0UT,*ENDWAIT=-G0IN 
-NXTLINE 
; * ADD 1 TO THE COUNTER FOR NUMBER OF LINES PROCESSED 
&MSZI = &MSZI +1 

* IF THE NUMBER OF THE LINE TO BE PROCESSED IS GREATER THAN THE 

< * NUMBER IF LINES IN THE MESSAGE, THEN DISPLAY THE RESULTS 
&IF &MSZI = &NUMLINES &THEN &GOTO -ENDIT 

* ASSIGN THE TEXT OF THE NEXT LINE €F THE MESSAGE TO MSGTXT 
GETMLINE MSGTXT &MSZI 

I * PARSE MSGTXT SO THAT THE MESSAGE ID OF THE LINE IS PLACED IN 
; * THE MSGID VARIABLE. 

PARSEL2R MSGTXT MSGID MSGSTR 

&IF &MSGID = DSI642I &THEN &GOTO -ENDIT 

&IF &MSGID = DSI643I &THEN &GOTO -NOEXIT 
■ &IF &MSGID = DSI636I &THEN &GOTO -COUNTER : U; 
I &GOTO -NXTLINE 

Figure 117 (Part 1 of 2). Command List Using Multi-Line Messages - NetView Command 

List Language Example 
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-NOEXIT J 

* THIS INSURES THAT THE OPERATOR IS INFORMED OF THE RESULTS OF J 

* THE COMMAND WHEN NO MESSAGES HAVE BEEN ASSIGNED, BUT THE ? 

* MESSAGE INFORMING THE OPERATOR HAS BEEN SUPPRESSED f 
&IF .&OPT = .SUPPRESS &THEN &GOTO -ENDIT i 
&EXIT \ 
-COUNTER I 

* IF THE FIRST MESSAGE LINE IS BEING PROCESSED, DETERMINE THE NUMBER | 

* OF LINES FOR THE MESSAGE \ 
IF &MSZI = 1 &THEN &GOTO -LINES 

-COUNTER1 | 

* TOTAL THE NUMBER OF MESSAGES ASSIGNED TO PRIMARY RECEIVERS <:\ 
&COUNT = &COUNT +1 1 
&GOTO -NXTLINE 2 
-LINES \ 

* ASSIGN THE NUMBER OF LINES IN THE MESSAGE TO THE VARIABLE NUMLINES f 
GETMSIZE NUMLINES 1 
&GOTO -COUNTER1 

-GOIN I 

&WRITE COMMAND LIST AUTHTOTE ENDED BY "GO" COMMAND — COUNT INCOMPLETE 4 

&EXIT 

-TIMEOUT 

&WRITE NO RESPONSE WITHIN 60 SECONDS. COMMAND LIST TERMINATING 

&EXIT J 

-ENDIT 

* DISPLAY THE COUNT OF MESSAGES ASSIGNED TO AUTH RECEIVERS ■. A 
&WRITE &COUNT MESSAGE(S) ASSIGNED TO SPECIFIC AUTH RECEIVERS 

&EXIT 

Figure 117 (Part 2 of 2). Command List Using Multi-Line Messages - NetView Command 

List Language Example 



Using the SDOMAIN Command with the QUIET Option 

This section describes general-use programming interfaces, which allow the cus- 
tomer to write programs that use the services of the NetView program. This 
section ends where "Hints for Implementing Message Automation" on page 161 
begins. 

The hardware monitor sdomain command can be issued with the quiet option from 
a command list, to set the domain and return a message for automation. To trap 
the message in a rexx command list, issue the sdomain command after issuing a 
trap instruction but before issuing a wait command. To trap the message in a 
command list written in the NetView command list language, issue the sdomain 
command from the &wait statement. 

NetView supplies a sample command list written in the NetView command list lan- 
guage that issues this command (see Figure 118 on page 159). In this command 
\ list, whenever an sdomain message occurs that is not tested on the &wait state- 



f 



ment, the message is written to the command facility panel and the command list 
stops execution. 

The most common messages produced by the sdomain command are: 
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BNJ911I Current domain now xxxx, was yyyy 

BNJ912I Attempting a cross domain session to an incompatible level of NetView 

BNJ924I Attempting a cross domain session with an undefined domain 

BNJ926I sd/sdomain command failed, current domain is unchanged. 

Figure 118 is an example of how to invoke the sdomain command with the quiet 
option from a command list. 



r CLIST 

I &C0NTR0L ERR 

!" *************************************************** 

* (C) COPYRIGHT IBM CORP. 1988 * 

* LAST CHANGE: * 
: * DESCRIPTION: THIS COMMAND LIST ISSUES THE SOOMAIN QUIET COMMAND * 
\ * WHICH INITIATES A CROSS DOMAIN SESSION WITHOUT * 
F * DISPLAYING THE NPDA MAIN MENU. IF THE SDOMAIN QUIET * 
: ■ * COMMAND IS SUCCESSFUL, THE ALERTSD COMMAND IS ISSUED. * 

* CNMEG044 CHANGED ACTIVITY: * 

* CHANGE CODE DATE DESCRIPTION * 

* „__ * 

************************************************************************ 

! * THE FIRST (AND ONLY) PARAMETER EXPECTED BY THIS COMMAND LIST IS THE * 

* DOMAIN NAME FOR WHICH THE ALERTSD INFORMATION IS DESIRED. * 

************************************************************************ 

&D0MAINID - &1 
************************************************************************ 

* * IF A DOMAIN NAME IS NOT PASSED TO THE COMMAND LIST, THEN SET THE * 

* DOMAIN NAME TO THE DOMAIN THE USER IS LOGGED ONTO. * 

************************************************************************ 

&IF .&DOMAINID NE . &THEN &G0T0 -XDOMAIN 
&D0MPART = &LENGTH &APPLID 
&D0MPART - &D0MPART - 3 

&D0MAINID = &SUBSTR &APPLID 1 &D0MPART 

************************************************************************ 

f * INVOKE THE SDOMAIN COMMAND WITHIN THE &WAIT STATEMENT TO TRAP THE * 

; * MESSAGES PUT OUT BY HARDWARE MONITOR. * 

************************************************************************ 

? -XDOMAIN 

1 &WAIT CONTWAIT SUPPRESS 

; &WAIT 'NPDA SDOMAIN &D0MAINID QUIET' + 

; c BNJ911I=-NPDACM + 

I BNJ912I=-INC0MPAT + 

I BNJ924I=-BADXDOM + 

i BNJ926I=-SDFAIL + 

I' *ERR0R=-ERR0R + 

f *10=-TIME0UT 

\ &G0T0 -ERROR 

Figure 118 (Part 1 of 2). NetView Command List Language Command List Issuing 

SDOMAIN with QUIET option 
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**************************************************************** 

* DISPLAY APPROPRIATE MESSAGE * \ 
************************************************************************ i 

■ ** J 

** CROSS DOMAIN SESSION TO AN INCOMPATIBLE LVL OF NETVIEW WAS ATTEMPTED | 

-INCOMPAT I 

■ GO I 

&WRITE IN CNME0044: &MSGIB &MSGSTR I 

&GOTO -END j 

** 

** CROSS DOMAIN SESSION TO AN UNDEFINED DOMAIN WAS ATTEMPTED 

:.■•-**'"'- 2 

-BADXDOM 

&WRITE IN CNME0044: &MSGID &MSGSTR \ 

&WAIT CONTINUE 

** s . 

** THE SDOMAIN COMMAND FAILED 
**■ 

-SDFAIL 

! go-: 

&WRITE IN CNMEG044: &MSGID &MSGSTR 

&GGTO -END i 

• ** 

** AN UNEXPECTED ERROR OCCURRED 

**■ '.,'■. 

-ERROR l : 

&WRITE IN CNME0044: UNDETERMINED ERROR OCCURRED 

&GOTO -END 

. . **■ .'•■.- 

** &WAIT TIMED OUT BEFORE ANY MESSAGES IT WAS TESTING FOR OCCURRED 

** 

-TIMEOUT 

&WRITE IN CNME0044: TIME OUT ON SDOMAIN COMMAND 

&GGTO -END 
************************************************************************ 

* SDOMAIN COMMAND WORKED CORRECTLY, ISSUE THE ALERTS DYNAMIC COMMAND * \ 

************************************************************************ 

-NPDACM 
NPDA ALERTSD 

&GQTO -END 

************************************************************************ 

* END OF COMMAND LIST * 1 
************************************************************************ 

-END i 

&EXIT I 

Figure 118 (Part 2 of 2). NetView Command List Language Command List Issuing 

SDOMAIN with QUIET option 
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Hints for Implementing Message Automation 

This section provides suggestions to help you effectively implement message auto- 
mation. 

Suppressing Messages 

You can suppress some messages so that the operator never receives them. To 
suppress messages with NetView message automation, make an entry in the 
message automation member. Assume, for instance, that you do not want the 
message 1ST4001 termination in progress for applid applnm to be displayed. 
Figure 119 shows what the message automation statement looks like. 



£ IF MSGID='IST40Or THEN DISPLAY(N); 
Figure 119. Message Automation Statement to Suppress Message 



Determining What Task Controls a Command List 

If you are not sure what type of task a command list will run under, have the 
command list check theTASKO function or &task control variable in the beginning of 
the command list. You can then use conditional processing to make the command 
list flexible enough to run differently under different tasks. See REXX User's Guide 
and REXX Reference or Chapter 7, "NetView Command List Language Branching" 
on page 107 for more information about conditional processing. 

Testing Automation Command Lists 

You can test command lists invoked from the message automation table by using 
say in rexx command lists or &write or &begwrite in command lists written in the 
NetView command list language. This method works if the message automation 
table does not check for the message type (hdrmtypeo or &hdrmtype) or the 
optional system information. For example, you can send a message to an auto- 
mation task to trigger the message-driven command list under that automation 
task. This allows you to test your automation command lists by enabling you to 
send messages that you expect the command list to handle during regular proc- 
essing. 

Figure 120 shows an example of a rexx command list using the say instruction that 
you could use to generate test messages. 



I /* COMMAND LIST TO TEST AUTOMATION COMMAND LISTS */ 

I TRACE ERRORS 

t PARSE AR6 FARMS 

I SAY PARMS 

t EXIT 

!-■"•■•" , ■ <...-. ■..-.,■., ■,.'''.'■.-...■ -■'■ ■■■■-■■ —■■.<■ ..<,.■ . ■■■■■-•*■■•■■ ■■,■-' ■• .■ ; 

Figure 120. REXX Command List to Test Automation Command Lists 

Figure 121 on page 162 shows an example of a command list written in the 
NetView command list language using &write that you could use to generate test 
messages. 
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TESTMSG CLIST 

&CDNTRQL ERR 
&WRITE &PARMSTR 
&EXIT 

Figure 121. NetView Command List Language Command List to Test Automation 
Command Lists 

You can then test the text of any single line message by typing the following as a 
NetView command, or within another command list: 

TESTMSG your message text here 

Figure 122 is a rexx command list that shows how to use the say instruction to gen- 
erate a multiple-line message: 



/* COMMAND LIST TO TEST MULTIPLE LIME MESSAGES */ 
TRACE ERRORS 
SAY , 
IEE000I THIS IS A TEST MULTIPLE LINE MESSAGE 
THIS IS LINE 2 
THIS IS LIRE 3 
THIS IS LINE 4 

THIS IS THE LAST LINE FOR IEE0O0I' 
EXIT 



Figure 122. REXX Command List to Generate a Multiple-Line Message 

Note: There must be 67 characters or blanks enclosed by the single quotes on 
each line of the say instruction, except the last line. 

Figure 123 is a command list written in the NetView command list language that 
shows how to use &begwrite to generate a multiple-line message: 



TESTMLN CLIST 

&C0NTROL ERR 

&BEGWRITE -ENDLINE 
IEE000I THIS IS A TEST MULTIPLE LINE MESSAGE 

THIS IS LINE 2 

THIS IS LINE 3 

THIS IS LINE 4 

THIS IS THE LAST LINE FOR IEE000I 
-ENDLINE 

&EXIT 



Figure 123. NetView Command List Language Command List to Generate a Multiple-Line 
Message 

In this example, it is necessary to type the message text into the command list 
before running, so the multiple-line message format can be produced. You can run 
the command list by typing testmln as a NetView command. 
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Recovering From Looping Command Lists 

It is possible to write command lists that will loop. For example, if you write a 
command list that is driven by a message issued by a command in the same 
command list, looping will occur. If a looping message-driven rexx command list 
has a wait, or a looping message-driven NetView command list language command 
list has an &wait or &pause, issue the stack command from the operator's console 
to recover. Then turn off message automation with the command automsg off. If 
there is no wait in a rexx command list or &wait or &pause in a command list written 
in the NetView command list language, you can issue the automsg off command 
from your terminal. Once the looping has stopped, you can revise the command 
list. 

Considering Operator Interaction 

Command lists used for automation of unsolicited messages should not ask the 
operator for data. For example, a rexx command list using a wait or a NetView 
command list language command list using either &pause vars or &wait, requiring 
a go command, is inappropriate. Consider how messages from a command list 
affect operator requests, and try to make automation command lists interfere as 
little as possible because automation runs at the same time that operators enter 
requests. 

Other Common Automation Problems 

Message automation is invoked after the command facility exit routines (for 
example, dsiexo2A, dsiexo6, dsiexh) have been called, so changes made to mes- 
sages in these routines affect message automation. For example, if a message is 
deleted by dsiexo2a, NetView does not invoke automation for that message. If a 
message is assigned to sysop or log as the primary receiver, NetView does not 
invoke automation for that message. Since message automation does not occur in 
the preceding instances, the display keyword in the message automation member 
does not have any effect. 

If the message processing facility is used to suppress a message with auto=yes 
coded and this message is used to drive a command list, when the command list is 
driven and a wto is issued, the wto is also suppressed. You must change the 
setting of the mcsflagq function or the &mcsflag control variable for the wto to be 
displayed. See Figure 109 on page 150 for an example of how to change a func- 
tion or control variable. 

If a multi-line write-to-operator (mlwto) message is used to drive a command list 
and a wto is issued from the command list, the wto may or may not be displayed, 
depending on the setting of linetypeo or &linetype. You should check the setting of 
linetypeo or &linetype, and if your wto is a single line message, change the setting 
of linetypeo or &linetype to a blank. 
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How to Set Up for Migration 



NetView comes with a utility program called dsicnvrt that helps you in converting 
nccf, and NetView Release 1 message automation to NetView Release 3 message 
automation. You will find the jcl statements or vm exec to run the program in the 
NetView samplib. See the NetView Installation and Administration Guide for details 
on how to run the dsicnvrt utility. 

You must perform the following tasks when migrating to NetView Release 3 
message automation. 

For Migrating from NCCF to NetView Release 3: 

If you have any cmdmdl statements in dsicmd to support the nccf method of 
VTAM-only message automation, do one of the following: 

• For mvs systems, set up the input dd statement in your jcl to reference your 
dsicmd member. 

• For vm systems, set up the input filedef in the exec file to reference your dsicmd 
file. 

The dsicnvrt program produces a message automation statement in the file speci- 
fied as output for every cmdmdl that defines a command list starting with ist. 

For Migrating from NetView Release 1 to Release 3: 

If you have been using NetView Release 1 message automation, do one of the fol- 
lowing: 

• For mvs systems, set up the input and output dd statements in your jcl for each 
message automation member and then run dsicnvrt to convert each of them. 

• For vm systems, set up the filedefs in your exec file for each message auto- 
mation member and then run dsicnvrt to convert each of them. 

For Both Types of Migration: 

Review the output of dsicnvrt to ensure that the command lists that it calls are con- 
sistent with your previously existing command lists. Make the necessary adjust- 
ments to take advantage of the extensions to message automation in Release 3. 

Conversion Considerations for MVS/OCCF 

If you are automating mvs messages using mvs/occf, pay extra attention to the con- 
version process. In mvs the job entry subsystems (JES2 and JES3) offset the actual 
text of a message by inserting a job identifier. If you coded your message auto- 
mation for mvs system messages using an offset to read the message id in the first 
column, instead of the mvs job id, you have to convert manually instead of using 
dsicnvrt. In NetView Release 3 the program offsets the job identifier in the 
message for you. When the mvs system message crosses the NetView interface, 
the message id starts in the first column. The job identifier is still available in the 
form of the function jobnumo in a rexx command list or the control variable 
&jobnum in a command list written in the NetView command list language. For 
more information about &jobnum, see "Message Processing Information" on 
page 84. Refer to "Message Processing Information" on page 53 for more infor- 
mation about jobnumq. 
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Chapter 10. Service Point Command Service Commands 

This chapter describes how to use the service point command service (spcs) com- 
mands in command lists. 



Service Point Command Service 



The service point command service is a set of commands that supports and 
enhances the NetView program's control of service points, for example, the 
NetView/PC™. A service point application manages non-SNA devices, such as 
front-end line switches and multiplexers. You can send commands to the service 
point application to do problem determination for these devices. 

There are four NetView spcs commands that are used with NetView/PC for problem 
determination: 

• linktest — requests that the service point test a given link or link segment. 

• linkdata — requests that the service point return device data for a given link or 
link segment. 

• linkpd — requests problem determination analysis from the service point on a 
given link or link segment. 

• runcmd — sends service point application commands to the service point appli- 
cations from NetView. 

See NetView Operation for the syntax of the linktest, linkdata, linkpd, and runcmd 
commands. 

The spcs commands are long running commands that suspend the command list 
when they are executed. The command list resumes when the spcs command is 
complete. 

Note: The rexx wait instruction and the NetView command list language &wait 
control statement should not be used with the spcs commands. Use message- 
driven command lists to trap messages generated from the spcs commands, with 
the exception of: 

• linkpd messages DS15331, DSI534I, DSI535I, DSi536i, and DSi582i. These five messages 
are set to values you can use in the form of control and parameter variables. 
See "LINKPD Results" on page 167 for more information on linkpd results. 

• Responses to runcmd with the clistvar keyword, clistvar causes the 
responses to be stored in variables. See "RUNCMD Results" on page 168 for 
more information on runcmd results. 



tm NetView/PC is a trademark of International Business Machines Corporation. 
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Service Point Command Service Return Codes 

After the command is completed, rc for command lists written in rexx or &retcode 
for command lists written in the NetView command list language contains one of 
the following values: 

Code Meaning 

The command succeeded. 

4 The command failed or clistvar was specified with runcmd and no 

response was returned. 
16 The command was cancelled by the cancmd. 
24 Some command list data was truncated. 

28 The service point application returned more than 132 responses for the 

runcmd with the clistvar keyword. 



LINKDATA and LINKTEST Results 



linkdata and linktest can be used in command lists to manage service points, for 
example NetView/PC. The formats of these commands can be found in NetView 
Operation. 

You can use the following linkdata and linktest variable names in your command 
lists. Use the variable name without the ampersand for rexx command lists. Use 
the variable name with the ampersand for NetView command list language 
command lists. The italicized letters in the variable names will be replaced with 
the following values: 

• pp — path number (01) 

• rr—- resource number (01-99) 

• ee — entry number (01-99). 

Note: Path number is always equal to '01' for linktest and linkdata. 

DSIPATHCNT or &DSIPATHCNT 

Number of paths returned. It is always equal to '01 ' for link com- 
mands. The path count is the origin of the value of pp in the following 
variable names. 

OSIppRC or &DSIppRC 

Number of resources for path pp. The resource count is the origin of 
the value of rr in the following variable names. 

DSlpprrEC or &DSIpprrEC 

Number of entries for resource rr on path pp. The entry count is the 
origin of the value of ee in the following variable names. 

DSIpprrRN or &DSIpprrRN 

Name of resource rr on path pp 

DSIpprrRT or ADSIpprrRT 

Type of resource rr on path pp 

DSIpprreeDN or &DSIpprreeDN 

Name of data item ee for resource rr on path pp 

DSIpprreeDT or &DSIpprreeDT 

Type of data item ee for resource rr on path pp. Possible values are: 

• BIT STRING 

• CHARACTER 
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• DECIMAL 

• HEXADECIMAL 

DSIpprreeDV or &DSIpprreeDV 

Value of data item ee for resource rr on path pp. 

LINKTEST Additional Variables 

In addition, linktest uses the following variables: 

DSIREQUEST or &DSIREQUEST 

Number of tests requested 

DSIACTUAL or &DSIACTUAL 

Actual number of tests executed 

DSITESTTYPE or &DSITESTTYPE 

Indication of the type of test data reported. Possible values are: 

• BACKGROUND 

• REQUESTED. 

DSIRESULT or &DSIRESULT 

Indication of the overall results of the test execution. Possible values 
are: 

• PASSED 

• FAILED 

• INDETERMINATE. 



LINKPD Results 



Results from the linkpd command are returned in messages that can be used in a 
command list to automate the recovery of resources controlled by a service point, 
for example, NetView/PC. linkpd results can be used as the rexx functions 

MSGCNT(), MSG!D(), MSGORIGN(), MSGSTR(), MSGTYP(), and MSGVAR(1) - MSGVAR(31), or the 

NetView command list language control variables &msgcnt, &msgid, &msgorign, 
&msgstr, &msgtyp, and the parameter variables &1 - &31. For more information 
about the rexx functions msgorigno, msgido, msgcnto, msgstro, and msgtypo, see 
"Message Processing Information" on page 53. For more information about 
msgvar(1) - msgvar(31), see "Functions Set by MSGREAD" on page 40. For more 
information about the NetView command list language control variables &msgcnt, 
&msgid, &msgorign, &MSGSTR, and &msgtyp see "Message Processing Information" 
on page 84. For more information about parameter variables used in command 
lists written in the NetView command list language, see "Parameter Variables" on 
page 77. 
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Advanced Topics 



RUNCMD Results 



If you use runcmd without the clistvar keyword, responses from the service point 
application that performed the runcmd are sent to the network operator's terminal, 
and a return code is set (rc or &retcode). See "Service Point Command Service 
Return Codes" on page 166 for a description of the different return codes. 

If you use runcmd with the clistvar keyword, the command results in the following: 

• A return code is set (rc or &retcode). See "Service Point Command Service 
Return Codes" on page 166 for a description of the different return codes. 

• If the command completes with a return code of 0, 24, or 28, the following vari- 
ables are set. Use the variable name without the ampersand for rexx 
command lists. Use the variable name with the ampersand for NetView 
command list language command lists. 

DSIRUNCNT or &DSIRUNCNT 

Contains the number of responses returned from the service point 
application. The variable has a value from 001 to 132. 

DSIRUNxxx or &DS!RUNxxx 

Contains the different responses from the service point application. 
The responses are numbered from 001 to 132. 

Note: The responses from the service point must be character data and cannot be 
longer 255 characters. 
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Appendix A. REXX Command List Reference Summary 

This appendix contains separate summary charts of the rexx instructions and func- 
tions provided by the NetView program. In each chart, the entries are listed in 
alphabetical order. 

In the instruction summary chart, the instruction is followed by its operands, a brief 
description, and where to find more information in this book. 

In the function table, the function is followed by its description and where to find 
more information in this book. 

A complete list of all rexx instructions and functions can be found in REXX Refer- 
ence or f?£XX User's Guide. 

Notes: 

1. In this book REXX Reference refers to TSO/E REXX Reference for mvs users or 
VM/SP System Product Interpreter Reference for vm users. 

2. In this book REXX User's Guide refers to TSO/E REXX User's Guide for mvs 
users or VMfSP System Product Interpreter User's Guide for vm users. 
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Table 3. REXX Instruction Summary 



Instruction 



Operands 



Description 



Location 



FLUSHQ 



f MESS AG ESI 



Removes all trapped 
messages from the 
message queue. 



See 

"REXX 

FLUSHQ 

Instruction' 

on 

page 42. 



GLOBALV 



PUTT var/ab/e[,...] 
GETT var/ao/e[,...] 



Sets and retrieves the 
variables specified as 
task global variables. 



See 

"REXX 

GLOBALV 

Instruction' 

on 

page 44. 



GLOBALV 



PUTC va/7ab/e[,...] 
GETC var/ab/e[,...] 



Sets and retrieves the 
variables specified as 
common global vari- 
ables. 



See 

"REXX 

GLOBALV 

Instruction' 

on 

page 44. 



MSGREAD 



None 



Reads a trapped 
message from the 
message queue. 



See 

"REXX 

MSGREAD 

Instruction" 

on 

page 40. 



TRAP 



[[AND ] SUPPRESSI DiSPLAYl l 

TMOREI ONLYI 

MESSAGES 

token [,...] 



Defines the messages 
to be trapped. 



See 

"REXX 

TRAP 

Instruction" 

on 

page 34. 



TRAP 



NO MESSAGES 



Indicates that the list of 
messages to be 
trapped that was speci- 
fied on a previous trap 
instruction should be 
removed. 



See 

"REXX 

TRAP 

Instruction" 

on 

page 34. 



WAIT 



[n rSECONDS iMlNUTESn 
[FOR [MESSAGES]] 



Causes a command list 
to temporarily suspend 
processing until a spe- 
cific event occurs. You 
must code a time 
interval, messages, or 
both. 



See 

"REXX 

WAIT 

Instruction" 

on 

page 36. 



WAIT 
CONTINUE 



None 



Causes a command list 
to continue waiting 
before resuming proc- 
essing. The options 
specified on the pre- 
vious trap and wait 
instructions remain in 
effect for wait continue. 



See 

"Contin- 
uing to 
Wait for 
Addi- 
tional 
Messages" 
on 
page 38. 
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Table 4 (Page 1 of 3). REXX Function Summary 



Function 



Value 



Location 



APPLIDQ 



The application program 
identifier for the task 
under which the command 
list is running (NetView 
domain id appended with 
a 3-character alphanu- 
meric value assigned by 
NetView). 



See "Session Information" on page 51. 



AREAIDQ 



A one-letter (A-Z) identi- 
fier for the area on the 
console screen that dis- 
plays the message. 



See "Message Processing Information' 
on page 53. 



COMPNAMEQ 



The 16-byte name of the 
component that was 
running when the 
command list was initi- 
ated. 



See "Command List Information" on 
page 53 



DESC() 



MSGCNT() 



The system descriptor 
codes in a binary series 
of on (1) and off (0) char- 
acters, representing the 
descriptor code bits in 
order. 



See "Message Processing Information' 
on page 53. 



EVENT() 


The NetView event that 
satisfied the wait instruc- 
tion. 


See "Checking the Result of a WAIT 
Instruction" on page 38. 


HCOPY() 


The name of the hard- 
copy log printer started by 
the operator. 


See "Terminal Information" on 
page 52. 


HDRMTYPE() 


The 1 -character NetView 
message type of the 
message. 


See "Message Processing Information" 
on page 53. 


JOBNAME() 


The 1- to 8-character mvs 
job name identifier. 


See "Message Processing Information" 
on page 53. 


JOBNUM() 


The 8-character mvs job 
number identifier. 


See "Message Processing Information" 
on page 53. 


LINETYPE() 


The multi-line write-to- 
operator (mlwto) line 
type. 


See "Message Processing Information" 
on page 53. 


LU() 


The logical unit name for 
this operator terminal. 


See "Terminal Information" on 
page 52. 


MCSFLAG() 


The system message 
flags in a binary series of 
on (1) and off (0) codes. 


See "Message Processing Information" 
on page 53. 



The number of elements 
of text in the message 
string of the last message 
read by msqread. 



See "Message Processing Information' 
on page 53. 



MSGID() 



The message id of the last 
message read by 

MSGREAD. 



See "Message Processing Information' 
on page 53. 
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Table 4 (Page 2 


of 3). REXX Function Summary 




Function 


Value 


Location 


MSGORIGN() 


The domain where the 
last message read by 
msgread originated. 


See "Message Processing Information" 
on page 53. 


MSGSTRQ 


The message text of the 
last message read by 

MSGREAD. 


See "Message Processing Information" 
on page 53. 



MSGTYP() 



The system message type 
presented as three con- 
secutive binary charac- 
ters. 



See "Message Processing Information' 
on page 53. 



MSGVAR(n) The value of each element 

of message text of the last 
message read by 

MSGREAD. 

The MSGVAR(n) functions 
can also be given values 
when a command list is 
invoked in the same way 
the &1 - &31 NetView 
command list language 
parameter variables can. 



See "Functions Set by MSGREAD" on 
page 40. 



NVCNT() 



The number of NetView 
domains with which you 
can establish a cross- 
domain session. 



See "Session Information" on page 51. 



NVID(n) 



The NetView domain iden- 
tifier of a domain with 
which you can establish a 
cross-domain session. 



See "Domain Information" on page 56. 



NVSTAT(name) 



Indicates whether you 
have an active session 
with a domain. 



See "Domain Information" on page 56. 



OPIDQ 



The operator's id. 



See "Operator Information" on 
page 52. 



OPSYSTEMQ 



A character string that 
indicates the operating 
system under which a 
command list is running. 



See "Session Information" on page 51 



PARMCNT() The number of parameter 

variables that were 
entered when a command 
list was initiated. 



See "Command List Information" on 
page 53. 



REPLYIDQ 



A three-character reply 
identifier for wtor 
command replies. 



See "Message Processing Information' 
on page 53. 



ROUTCDE() The system routing codes 

in a binary series of on (1) 
and off (0) characters, 
representing the routing 
code bits in order. 



See "Message Processing Information" 
on page 53. 
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Table 4 (Page 3 


of 3). REXX Function Summary 




Function 


Value 


Location 


SESSID() 


The id of the taf session 
that sent the message. 


See "Message Processing Information" 
on page 53. 


SMSGID() 


The 8-character value that 
identifies a particular 
instance of a message. 


See "Message Processing Information" 
on page 53. 


SYSCONID() 


The console number (in 
decimal) that is to receive 
a message. 


See "Message Processing Information" 
on page 53. 


SYSID() 


The identifier of the mvs 
system that sent the 
message. 


See "Message Processing Information" 
on page 53. 



TASK() 



The 3-character string ppt 
(primary poi task), ost 
(operator station task), or 
nnt (NetView-NetView 
task), depending on the 
task under which the 
command list is running. 
tasko allows the same 
command list to run under 
any of these tasks, 
because the command list 
can test for the task type 
and process accordingly. 



See "Session Information" on page 51. 



VTAM() 



A character string indi- 
cating the level of the 
access method used. 



See "Session Information" on page 51. 



WTOREPLY() 



The reply sent by the 
operator in response to a 
wtor command. 



See "Message Processing Information' 
on page 53. 
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Appendix B. NetView Command List Language Reference 
Summary 

This appendix contains separate summary charts of all control statements, control 
variables, and built-in functions used in the NetView command list language. In 
each chart, the entries are listed in alphabetical order. 

In the built-in function and control statement charts, the function or statement is fol- 
lowed by its operands, a brief description, and where to find more information in 
this book. 

In the control variable table, the variable is followed by its values and where to find 
more information in this book. 
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Table 5. Built-in Function Summary 



Function 



Operands 



Description 



Location 



&CONCAT 



variable variable 
constant constant 
variable constant 
constant variable 



Joins the values of two 
variables or constants to 
form a new value. 



See 

"&CONCAT 

Built-in 

Function" 

on 

page 100. 



&LENGTH 



variablejconstant 



Provides the number of 
characters in a variable 
or a constant. 



See 

"&LENGTH 

Built-in 

Function" 

on 

page 100. 



&NCCFID 



number 



Provides the identifier of a 
domain with which you 
can establish a cross- 
domain session. 



See 

"&NCCFID 

Built-in 

Function" 

on 

page 101. 



&NCCFSTAT 



domain 



Indicates whether you 
have an active session 
with a domain. 



See 

"&NCCFSTAT 

Built-in 

Function" 

on 

page 102. 



&SUBSTR 



variable start [length ] 



Puts part of a variable into 
another variable. 



See 

"&SUBSTR 

Built-in 

Function" 

on 

page 103. 
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Table 6 (Page 1 of 2). Control Statement Summary 



Control 
Statement 



Operands 



Description 



Location 



&BEGWRITE 



rsUBI NOSUB ] i-label ] 



Writes a series of mes- 
sages to the operator. 



See 

"&BEGWRITE 
Control 
Statement" 
on page 95. 



&CGLOBAL 



variable [,...] 



Defines the variables 
listed as common 
global variables. 



See 

"Common 

Global 

Variables" 

on 

page 126. 



&CONTROL 



fALL ICMDiERR ] 



Indicates which 
command list state- 
ments are displayed to 
the operator. 



See 

"&CONTROL 
Control 
Statement" 
on page 92. 



&EXIT 



[number ] 



Ends the command list. 



See "&EXIT 

Control 

Statement" 

on 

page 109. 



&GOTO 



■label 



Transfers control to 
another part of the 
command list. 



See 

"&GOTO 

Control 

Statement" 

on 

page 109. 



&IF 



comparison &then state- 
ment 



Tests a logical compar- See "&IF 

ison and takes action Control 

based on the results. If Statement" 

the comparison is true, on 

the &then clause is page 107. 

processed. 



&PAUSE 



NOINPUT I 
VARS variable [.. 
STRING variable 



Halts the command list 
until the operator types 
in go or reset. The 
operator can enter var- 
iables in the command 
list by coding them as 
operands on the go 
command. 



See 

"&PAUSE 
Control 
Statement" 
on page 97. 



&TGLOBAL 



variable [,...] 


Defines the variables 
listed as task global 
variables. 


See "Task 

Global 

Variables" 

on 

page 124. 


1' command '1 
event = -label [,...] 


Halts the command list 
until a specific 
message or group of 
messages is received. 


See 

"Coding an 

&WAIT 

Control 

Statement" 

on 

page 112. 



&WAIT 
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Table 6 (Page 2 of 2). Control Statement Summary 



Control 
Statement 



Operands 



Description 



Location 



&WAIT 



fDISPLAY ISUPPRESS ] 



Determines whether 
messages for the next 
&wait should be dis- 
played to the operator. 



See "Cus- 
tomizing 
the &WAIT 
Statement" 
on 
page 118. 



&WAIT 



[ENDWAJIICONTWAIT ] 



Establishes whether 
the next await can wait 
for more than one 
event. 



See "Cus- 
tomizing 
the &WAIT 
Statement" 
on 
page 118. 



&WAIT 



[CONTINUE ] 



Establishes whether 
the next &wait con- 
tinues waiting after the 
event has been satis- 
fied. 



See "Cus- 
tomizing 
the &WAIT 
Statement" 
on 
page 118 



&WRITE 



message text 



Sends a one-line 
message to the oper- 
ator. 



See 

"&WRITE 
Control 
Statement" 
on page 94. 
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Table 7 (Page 1 of 3). Control Variable Summary 



Variable 



&AREAID 



Value 



Location 



&APPLID The application program identifier for the See "Session 

task under which the command list is Information" on 

running (NetView domain id appended with page 82. 

a 3-character alphanumeric value assigned 
by NetView). 



A one-letter (A-Z) identifier for the area on 
the console screen that displays the 
message. 



See "Message 
Processing 
Information" on 
page 84. 



&COMPNAME The 16-byte name of the component that 

was running when the command list was 
initiated. 



See "Command 
List information" 
on page 83. 



&DATE 



&HCOPY 



The current date in the format MM/DD/YY. 



See "Time and 
Date" on page 81. 



&DESC The system descriptor codes in a binary See "Message 

series of on (1) and off (0) characters, Processing 

representing the descriptor code bits in Information" on 

order. page 84. 



The name of the hard-copy log printer 
started by the operator. 



See "Terminal 
Information" on 
page 83. 



&HDRMTYPE 



The 1-character NetView message type of 
the message. 



See "Message 
Processing 
Information" on 
page 84. 



&JOBNAME 



The 1- to 8-character mvs job name identi- 
fier. 



See "Message 
Processing 
Information" on 
page 84. 



&JOBNUM 



The 8-character mvs job number identifier. 



See "Message 
Processing 
Information" on 
page 84. 



&LINETYPE 



The multi-line write-to-operator (mlwto) line 
type. 



See "Message 
Processing 
Information" on 
page 84. 



&LU 



The logical unit name for the operator ter- 
minal. 



See "Terminal 
Information" on 
page 83. 



&MCSFLAG 



The system message flags in a binary 
series of on (1) and off (0) codes. 



See "Message 
Processing 
Information" on 
page 84. 



&MSGCNT 



The number of elements of text in a 
message string. 



See "Control and 
Parameter Vari- 
ables Used with 
&WAIT" on 
page 116. 
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Table 7 (Page 2 of 3). Control Variable Summary 



Variable 



Value 



Location 



&MSGID 



The message id of the message most 
recently received by NetView. 



See "Control and 
Parameter Vari- 
ables Used with 
&WAIT" on 
page 116. 



&MSGORIGIN The domain from which the message was 

sent. 



See "Control and 
Parameter Vari- 
ables Used with 
&WAIT" on 
page 116. 



The message text of the message most 
recently received by NetView. 



&MSGSTR 



See "Control and 
Parameter Vari- 
ables Used with 
&WAIT" on 
page 116. 



&MSGTYP 



&REPLYID 



The system message type presented as 
three consecutive binary characters. 



See "Message 
Processing 
Information" on 
page 84. 



&NCCFCNT 


The number of NetView domains with which 


See "Session 




the operator can establish a cross-domain 


Information" on 




session. 


page 82. 


&OPID 


The operator's id. 


See "Operator 
Information" on 
page 83. 


&OPSYSTEM 


A character string that indicates the oper- 


See "Session 




ating system under which a command list is 


Information" on 




running. 


page 82. 


&PARMCNT 


The number of parameter variables that 


See "Command 




were entered when a command list was ini- 


List Information" 




tiated. 


on page 83. 


&PARMSTR 


The string of parameter variables used 


See "Command 




when the command list was called. 


List Information" 
on page 83. 



A three-character reply identifier for wtor 
command replies. 



See "Message 
Processing 
Information" on 
page 84 



&RETCODE 



The return code set by either the most 
recent command processor or most 
recently activated or nested command list. 
The user can set &retcode with the &exit 
control statement to any positive value or to 
-1 . &retcode can be tested to determine 
command list processing. 



See "Command 
List Information" 
on page 83. 



&ROUTCDE 



The system routing codes in a binary series 
of on (1) and off (0) characters, repres- 
enting the routing code bits in order. 



See " Message 
Processing 
Information" on 
page 84 
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Table 7 (Page 3 of 3). Control Variable Summary 



Variable 



Value 



Location 



&SESSID 



The id of the taf session that sent the 
message. 



See Chapter 9, 
"Message 
Automation" on 
page 135 



&SMSGID 



The 8-character value that identifies a par- 
ticular instance of a message. 



See "Message 
Processing 
Information" on 
page 84. 



&SYSCONID 



The console number (in decimal) that will 
receive a message. 



See "Message 
Processing 
Information" on 
page 84. 



&SYSID 



The identifier of the mvs system that sent 
the message. 



See "Message 
Processing 
Information" on 
page 84. 



&TASK 



The 3-character string ppt (primary poi 
task), ost (operator station task), or nnt 
(NetView-NetView task), depending on the 
task under which the command list is 
running. &task allows the same command 
list to run under any of these tasks, 
because the command list can test for the 
task type and process accordingly. 



See "Session 
Information" on 
page 82. 



&TIME 


The cpu time in the format hh:mm. 


See "Time and 
Date" on page 81. 


&VIEWAID 


The aid key that the operator used to enter 


See "Panel 




panel input. 


Information" on 
page 87. 


&VIEWCURCOL 


The panel column where the cursor was 


See "Panel 




positioned when the aid key was pressed. 


Information" on 
page 87. 


&VIEWCURROW 


The panel row where the cursor was posi- 


See "Panel 




tioned when the aid key was pressed. 


Information" on 
page 87. 


&VTAM 


A character string indicating the level of the 


See "Session 




access method used. 


Information" on 
page 82. 



&WTOREPLY 



The reply sent by the operator in response 
to a wtor command. 



See "Message 
Processing 
Information" on 
page 84. 



&1 - &31 



The value of each element of message text 
of the last message received by NetView. 
&1 -&31 can also be given values when a 
command list is invoked. 



See "Control and 
Parameter Vari- 
ables Used with 
&WAIT" on 
page. 11 6. 
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Appendix C. Comparison of REXX and NetView Command 
List Language 

This appendix provides a quick comparison between the features of rexx and the 
NetView command list language. 

Comparison of REXX Instructions and NetView Command List 
Language Control Statements 

Table 8 on page 186 shows the task performed by each control statement used in 
the NetView command list language and provides the equivalent rexx instruction. 
The table is in alphabetical sequence based on the name of the NetView command 
list language control statement. The last column of the table indicates whether the 
corresponding rexx instruction is a standard instruction provided by rexx or 
whether it is an instruction provided by the NetView program. If the instruction is a 
standard rexx instruction, an r appears in this column. If the instruction is pro- 
vided by the NetView program, an n appears in this column. Instructions provided 
by the NetView program can only be used in conjunction with NetView. These 
instructions are not supported by the rexx interpreter and cannot be used in rexx 
execs executed in a non-NetView environment. 
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Table 8 (Page 1 of 2). Comparison of NetView Command List Language Control State- 
ments and REXX Instructions 



NetView 








Pro- 


Control State- 




REXX 




vided 


ment 


Task 


Instruction 


Task 


By 


&BEGWRITE 


Writes a series of 
messages to the 
operator. 


None 


Use the rexx say 
instruction or the 
NetView view 
command. 


R/N 


&CGLOBAL 


Defines the vari- 
ables listed as 
common global vari- 
ables. 


GLOBALV 


Sets and retrieves 
global variables. 


N 


&CONTROL 


Indicates which 
command list state- 
ments are displayed 
to the operator. 


TRACE 


Indicates whether 
the result of each 
expression is dis- 
played to the oper- 
ator. 


R 


&EXIT 


Ends the command 
list. 


EXIT 


Ends the command 
list. 


R 


&GOTO 


Transfers control to 
another part of the 
command list. 


SIGNAL 


Transfers control to 
another part of the 
command list. 


R 


&IF 


Tests a logical com- 
parison and takes 
action based on the 
results. If the com- 
parison is true, the 
&then clause is 
processed. 


IF 


Tests a logical com- 
parison and takes 
action based on the 
results. If the com- 
parison is true, the 
then clause is proc- 
essed. 


R 


&PAUSE 


Halts the command 


PARSE 


Reads the next 


R 




list until the oper- 


EXTERNAL 


string from the ter- 






ator types in go or 




minal input buffer 






RESET. 




(system external 
event queue). 






PARSE 


Reads the next 


R 






PULL 


string from the 
program stack 
(system-provided 
data queue). 





&TGLOBAL 



Defines the vari- 
ables listed as task 
global variables. 



GLOBALV 



Sets and retrieves 
global variables. 
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Table 8 (Page 2 of 2). Comparison of NetView Command List Language Control State- 
ments and REXX Instructions 



NetView 








Pro- 


Control State- 




REXX 




vided 


ment 


Task 


instruction 


Task 


By 



&WAIT 



Halts the command 
list until a specific 
message or group 
of messages is 
received. 



TRAP 



WAIT 



Defines the mes- 
sages to be trapped. 
Trapped messages 
can later be used in 
conjunction with the 

MSGREAD and WAIT 

instructions to 
control command 
processing. 



Halts the command 
list until a specific 
event occurs. The 
event can be one or 
more messages, a 
specific period of 
time, or both. The 
evento function can 
be used to deter- 
mine the result of 
the wait command. 



WAIT 


Causes the 


N 


CONTINUE 


command list to 
wait for additional 
messages before 
resuming proc- 
essing with the 
statement after the 

WAIT CONTINUE. 




MSGREAD 


Causes trapped 
messages to be 
read. 


N 



FLUSHQ Removes all 

trapped messages 
from the message 
queue. 



&WRITE 



Sends a one-line 
message to the 
operator. 



SAY 



Sends a one-line or 
multiple-line 
message to the 
operator. The rexx 
say instruction can 
have a character 
string of any length; 
however, NetView 
will output only 
32,728 characters at 
a time. 
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Comparison of REXX Functions and NetView Command List 
Language Control Variables 



Table 9 shows the tasks performed by the various control variables used in the 
NetView command list language and the equivalent rexx functions. The last 
column of the table indicates if the rexx function is a standard function provided by 
rexx or if it is a function provided by the NetView program. If the function is pro- 
vided by the NetView program, it can only be used in conjunction with NetView and 
is not supported by rexx. 

Table 9 (Page 1 of 5). Comparison of REXX Functions and NetView Command List Lan- 
guage Control Variables 











Pro- 


NetView Control 




REXX Func- 




vided 


Variable 


Task 


tion 


Task 


By 


&APPLID 


The application 
program identi- 
fier for the task 
under which the 
command list is 
running. 


APPLID() 


The application 
program identi- 
fier for the task 
under which the 
command list is 
running. 


N 


&AREAID 


A one-letter (A-Z) 
identifier for the 
area on the 
console screen 
that displays the 
message. 


AREAIDO 


A one-letter (A-Z) 
identifier for the 
area on the 
console screen 
that displays the 
message. 


N 


&COMPNAME 


The 16-byte 
name of the com- 
ponent that was 
running when the 
command list 
was initiated. 


COMPNAME() 


The 16-byte 
name of the com- 
ponent that was 
running when the 
command list 
was initiated. 


N 


&CONCAT 


Joins the values 
of two variables 
or constants to 
form a new 
value. 


II 


Joins the values 
of two variables 
or constants to 
form a new 
value. 


R 


&DATE 


The current date 
in the format 
mm/dd/yy. 


DATE() 


The local date in 
various formats. 


R 


&DESC 


The system 
descriptor codes 
in a binary series 
of on (1) and off 
(0) characters, 
representing the 
descriptor code 
bits in order. 


DESC() 


The system 
descriptor codes 
in a binary series 
of on (1) and off 
(0) characters, 
representing the 
descriptor code 
bits in order. 


N 


&HCOPY 


The name of the 
hard-copy log 
printer started by 
the operator. 


HCOPY() 


The name of the 
hard-copy log 
printer started by 
the operator. 


N 
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Table 9 (Page 2 of 5). Comparison of REXX Functions and NetView Command List Lan- 
guage Control Variables 











Pro- 


NetView Control 




REXX Func- 




vided 


Variable 


Task 


tion 


Task 


By 


&HDRMTYPE 


The 1 -character 
NetView 

message type of 
the message. 


HDRMTYPE() 


The 1-character 
NetView 

message type of 
the message. 


N 


&JOBNAME 


The 1- to 
8-character mvs 
job name identi- 
fier. 


JOBNAME() 


The 1- to 
8-character mvs 
job name identi- 
fier. 


N 


&JOBNUM 


The 8-character 
mvs job number 
identifier. 


JOBNUM() 


The 8-character 
mvs job number 
identifier. 


N 


&LENGTH 


Determines how 
many characters 
are in a variable 
or a constant. 


LENGTH 


Determines how 
many characters 
are in a variable 
or a constant. 


R 


&LINETYPE 


The multi-line 
write-to-operator 
(mlwto) line type. 


LINETYPE() 


The multi-line 
write-to-operator 
(mlwto) line type. 


N 


&LU 


The logical unit 
name for this 
operator ter- 
minal. 


LU() 


The logical unit 
name for this 
operator ter- 
minal. 


N 


&MCSFLAG 


The system 
message flags in 
a binary series of 
on (1) and off (0) 
codes. 


MCSFLAG() 


The system 
message flags in 
a binary series of 
on (1) and off (0) 
codes. 


N 


&MSGCNT 


The number of 
elements of text 
in a message 
string. 


MSGCNT() 


The number of 
elements of text 
in the message 
string of the last 
message read by 

MSGREAD. 


N 


&MSGID 


The message id 
of the message 
most recently 
received by 
NetView. 


MSGID() 


The message id 
of the last 
message read by 

MSGREAD. 


N 


&MSGORIGIN 


The domain from 
which the 
message was 
sent. 


MSGORIGNO 


The domain 
where the last 
message read by 
msgread origi- 
nated. 


N 



&MSGSTR 



The message text 
of the message 
most recently 
received by 
NetView. 



MSGSTR() 



The message text 
of the last 
message read by 
msgread. 



N 
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Table 9 (Page 3 of 5). Comparison of REXX Functions and NetView Command List Lan- 
guage Control Variables 











Pro- 


NetView Control 




REXX Func- 




vided 


Variable 


Task 


tion 


Task 


By 


&MSGTYP 


The system 
message type 
presented as 
three consec- 
utive binary char- 
acters. 


MSGTYPO 


The system 
message type 
presented as 
three consec- 
utive binary char- 
acters. 


N 


&NCCFCNT 


The number of 
NetView domains 
with which you 
can establish a 
cross-domain 
session. 


NVCNT() 


The number of 
NetView domains 
with which you 
can establish a 
cross-domain 
session. 


N 


&NCCFID 


The NetView 
domain identifier 
of a domain with 
which you can 
establish a cross- 
domain session. 


NVID(n) 


The NetView 
domain identifier 
of a domain with 
which you can 
establish a cross- 
domain session. 


N 


&NCCFSTAT 


Indicates 
whether you 
have an active 
session with a 
domain. 


NVSTAT(name) 


Indicates 
whether you 
have an active 
session with a 
domain. 


N 


&OPID 


The operator's id. 


OPID() 


The operator's id. 


N 


&OPSYSTEM 


A character 
string that indi- 
cates the oper- 
ating system 
under which a 
command list is 
running. 


OPSYSTEM() 


A character 
string that indi- 
cates the oper- 
ating system 
under which a 
command list is 
running. 


N 


&PARMCNT 


The number of 
parameter vari- 
ables that were 
entered when a 
command list 
was initiated. 


PARMCNT() 


The number of 
parameter vari- 
ables that were 
entered when a 
command list 
was initiated. 


N 


&PARMSTR 


The string of 
parameter values 
used when the 
command list 
was initiated. 


ARG(1) 


The string of 
arguments used 
when the 
command list 
was initiated. 


R 


&REPLYID 


A three-character 
reply identifier 
for WTOR 
command 
replies. 


REPLYIDQ 


A three-character 
reply identifier 
for WTOR 
command 
replies. 


N 
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Table 9 (Page 4 of 5). Comparison of REXX Functions and NetView Command List Lan- 
guage Control Variables 











Pro- 


NetView Control 




REXX Func- 




vided 


Variable 


Task 


tion 


Task 


By 


&RETCODE 


The return code 
set by either the 
most recent 
command 
processor or 
most recently 
activated or 
nested command 
list. 


RC 


The return code 
set by the most 
recently exe- 
cuted host 
command or sub- 
command or the 
most recently 
activated or 
nested command 
list. 


R 


&ROUTCDE 


The system 
routing codes in 
a binary series of 
on (1) and off (0) 
characters, 
representing the 
routing code bits 
in order. 


ROUTCDE() 


The system 
routing codes in 
a binary series of 
on (1) and off (0) 
characters, 
representing the 
routing code bits 
in order. 


N 


&SESSID 


The id of the taf 
session that sent 
the message. 


SESSID() 


The id of the taf 
session that sent 
the message. 


N 


&SMSGID 


The 8-character 
value that identi- 
fies a particular 
instance of a 
message. 


SMSGID() 


The 8-character 
value that identi- 
fies a particular 
instance of a 
message. 


N 


&SUBSTR 


Puts part of a 
variable into 
another variable. 


SUBSTR 


Puts part of a 
variable into 
another variable. 


R 


&SYSCONID 


The console 
number (in 
decimal) that will 
receive a 
message. 


SYSCONID() 


The console 
number (in 
decimal) that will 
receive a 
message. 


N 


&SYSID 


The identifier of 
the mvs system 
that sent the 
message. 


SYSID() 


The identifier of 
the mvs system 
that sent the 
message. 


N 


&TASK 


The 3-character 
string ppt 
(primary POI 
task), ost (oper- 
ator station task), 

or NNT 

(NetView-NetView 
task), depending 
on the task under 
which the 
command list is 
running. 


TASK() 


The 3-character 
string ppt 
(primary POI 
task), ost (oper- 
ator station task), 
or NNT 

(NetView-NetView 
task), depending 
on the task under 
which the 
command list is 
running. 


N 
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Table 9 (Page 5 of 5). Comparison of REXX Functions and NetView Command List Lan- 
guage Control Variables 











Pro- 


NetView Control 




REXX Func- 




vided 


Variable 


Task 


tion 


Task 


By 


&TIME 


The cpu time in 
the format 
hh:mm. 


TIMEQ 


The cpu time in 
various formats. 


R 



&VTAM 



A character 
string indicating 
the level of the 
access method 
used. 



VTAM() 



A character 
string indicating 
the level of the 
access method 
used. 



&WTOREPLY 



The reply sent by 
the operator in 
response to a 
wtor command. 



WTOREPLYO 



The reply sent by 
the operator in 
response to a 
wtor command. 



&1 - &31 



The value of each 
element of 
message text of 
the last message 
received by 
NetView. These 
variables can 
also be given 
values when the 
command list is 
invoked. 



MSGVAR(n) 



The value of each 
element of 
message text of 
the last message 
read by msgread. 
These variables 
can also be given 
values when the 
command list is 
invoked. 



192 NetView Customization: Writing Command Lists 



Commands Used in Command Lists 

Following is a list of NetView commands that are for use in command lists. These 
commands can be used in command lists written either in rexx or the NetView 
command list language. When using the commands in a rexx command list, you 
should enclose the parts of the command that you do not want variable substitution 
to take place on in single quotes. The list shows where in the book the command 
is described: 

DOM See "DOM" on page 141. 

GETMLINE See "GETMLINE" on page 154. 

GETMSIZE See "GETMSIZE" on page 152. 

GETMTYPE See "GETMTYPE" on page 153. 

MSGROUTE See "Routing Messages from Command Lists" on page 142. 

PARSEL2R See "Parsing Variables with PARSEL2R" on page 144. 

SDOMAIN (with QUIET option) 

See "Using the SDOMAIN Command with the QUIET Option" on 
page 158. 

WTO See "WTO" on page 138. 

WTOR See "WTOR" on page 140. 

Examples Comparing REXX and NetView Command List Language 

This section contains examples of command lists. Each example is first shown 
written in the NetView command list language. Following the NetView command 
list language example is an example of a rexx command list that performs the 
same functions. 
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GREETING Example— NetView Command List Language 



CLIST 

&C0NTR0L ERR 

************************************************ 

■■ **■ . . . •.-*■•■ 

* GREETING - SHOW SIMPLE EXAMPLE OF WAITING AND TRAPPING * 

* USING THE DATE COMMAND * 

* * 

* NOTE: WHEN DATE IS ENTERED, THE FOLLOWING IS RETURNED: * 

.*.'■■''■... ' • . ' . *< 

* CNM359I DATE : TIME = HH:MM DATE = MM/DD/YY * 
*********************************************************************** 

&WAIT SUPPRESS 

&WAIT 'DATE' CNM359I=-DATELAB,+ 

*1Q=-TIMEGUTLAB, + 

*ERROR=-ERRORLAB,+ 

*ENDWAIT=-GOLAB 
-DATELAB 

&HOUR = &SUBSTR &5 1 2 
&IF &H0UR >= 12 &THEN &GOTO -AFTER12 
&WRITE GOOD MORNING 
&GOTQ -EXIT 
-AFTER12 

&IF &H0UR >= 18 &THEN &GOTO -AFTER18 
&WRITE GOOD AFTERNOON 
&GOTO -EXIT 
-AFTER18 

&WRITE GOOD EVENING 
&GOTO -EXIT 
-ERRORLAB 

&WRITE 'ERROR OCCURED WAITING FOR DATE COMMAND RESPONSE' 
&GOTO -EXIT 
-TIMEOUTLAB 

&WRITE 'NO MESSAGE RETURNED FROM DATE COMMAND' 
&GOTO -EXIT 
-GOLAB 
-EXIT 
&EXIT 

Figure 124. GREETING Example— NetView Command List Language 
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GREETING Example-REXX 



/••A***************************************************************** 



/* 






V 


/* GREETING - SHOW SIMPLE EXAMPLE OF WAITING AND TRAPPING 


V 


/* USING THE DATE COMMAND 
/* 




V 
*/ 

V 

V 
7 


/ 

/* NOTE: WHEN DATE IS ENTERED, THE FOLLOWING IS RETURNED: 

/* 


/ 

/* CNM359I DATE : TIME - HH:MM 




DATE = MM/DD/YY 


/********************************************^ 


'TRAP AND SUPPRESS ONLY MESSAGES 


CNM359I ' /* TRAP DATE MESSAGE 


V 


•DATE' 


/* 


ISSUE COMMAND 


V 


'WAIT 10 SECONDS FOR MESSAGES' 


/* 


WAIT FOR ANSWER 


*/ 


SELECT 


/* 


RESULT IS BACK, PROCESS IT... 


V 


WHEN (EVENT ()='M') THEN 


/* 


DID WE GET A MESSAGE? 


*/ 


DO 


/* 


YES... 


V 


'MSGREAD' 


/*' 


... READ IT IN 


V 


H0UR=SUBSTR(MSGVAR{5) ,1,2) 


/* 


... PARSE OUT THE HOUR 


V 


SELECT 


/* 


GIVE APPROPRIATE GREETING... 


*/ 


WHEN (H0UR<12) THEN 


/* 


...BEFORE NOON? 


V 


SAY 'GOOD MORNING' 








WHEN (H0UR<18) THEN 


/* 


...BEFORE SIX? 


V 


SAY 'GOOD AFTERNOON' 








OTHERWISE 


/* 


. . .MUST BE NIGHT 


V 


SAY 'GOOD EVENING' 








END 


/* 


OF SELECT 


V 


END 


/* 


OF DO 


V 


WHEN (EVENT()='E') THEN' 


/* 


DID WE GET AN ERROR? 


V 


SAY 'ERROR OCCURED WAITING 


FOR DATE COMMAND RESPONSE' 




WHEN (EVENT()='T') THEN 


/* 


DID WE GET A TIMEOUT? 


V 


SAY 'NO MESSAGE RETURNED FROM DATE COMMAND' 




OTHERWISE 








END 


/* 


OF SELECT 


V 



Figure 125. GREETING Example-REXX 



Appendix C. Comparison of REXX and NetView Command List Language 195 



LISTVAR Example— NetView Command List Language 



CLIST 
&C0NTR0L ERR 

* SEE THE NETVIEW OPERATIONS MANUAL AND/OR ENTER HELP CLISTNAME 

* FOR A DESCRIPTION OF FUNCTION AND SYNTAX FOR THIS CLIST. 

************************************************************** 

* (C) COPYRIGHT IBM CORP. 1986, 1987 * 

* * 

* LAST CHANGE: 05/16/86 13:22:07 SSI=61361322 * 

* * 

* IEBCOPY SELECT MEMBER=((CNME1006,LISTVAR,R)) * 

*•.••■: * 

* OUTPUTS: * 

*.•'■■ CNM353I. *■ 

* * 

* CNME1006 CHANGED ACTIVITY: *. 
*•• CHANGE CODE DATE DESCRIPTION * 

* — .' -« -— * 

'.*'■'.■ * 

*********************************************************************** 

&CONTROL ERR 
************************************************************************ 

* IF PARM IS A ? THEN GOTO HELP. OTHERWISE SHOW VARIABLES AND * 

* VALUES. 

&IF .&1 EQ .? &THEN &GOTO -HELP 
&IF .&! NE . &THEN &GOTO -ERROR 
&WRITE CNM353I LISTVAR : 'OPSYSTEM' = &OPSYSTEM 
&WRITE CNM353I LISTVAR : 'VTAMLVL 1 = &VTAM 
&WRITE CNM353I LISTVAR : 'APPLID' = &APPLID 
&WRITE CNM353I LISTVAR : 'OPID r = &OPID 
&WRITE CNM353I LISTVAR : 'LU' = &LU 
&WRITE CNM353I LISTVAR : 'TASK' = &TASK 
&WRITE CNM353I LISTVAR : 'DATE' = &DATE 
&WRITE CNM353I LISTVAR : 'TIME' = &TIME 
&WRITE CNM353I LISTVAR : 'NCCFCNF = &NCCFCNT 
&WRITE CNM353 I LISTVAR : 'HCOPY' = &HCOPY 
&IF .&VTAM = «.' &THEN &GOTO -MSG 

&EXIT 

************************************************************************ 

-ERROR 

MESSAGE 306E,LISTVAR,&1 

&EXIT 

************************************************************************ 

-MSG 

&WRITE CNM386I LISTVAR : VTAM IS NOT ACTIVE AT THIS TIME 

&EXIT 

************************************************************************ 

-HELP 

HELP LISTVAR 

&EXIT 

Figure 126. LISTVAR Example— NetView Command List Language 
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LISTVAR Example-REXX 



/•A***************************************************************** 
/* */ 

/* THE LISTVAR COMMAND LIST WRITTEN IN REXX */ 

/* */ 

/****************************•**********************•********* 

SELECT 
WHEN MSGVARdK?' THEN /* HELP REQUESTED ? */ 

•HELP LISTVAR' /* GO GET HELP */ 

WHEN MSGVAR(1)-='V THEN /* ANY PARMS SPECIFIED ? */ 

'MESSAGE aoeE/LISTVAR' MSGVAR(l) /* NO PARMS ALLOWED */ 
OTHERWISE /* ALL OK, LIST OUT VARIABLES*/ 

DO 

SAY "CNM353I LISTVAR : 'OPSYSTEM* = "OPSYSTEMO 

SAY "CNM353 I LISTVAR : 'VTAMLVL 1 - "VTAMQ 

SAY "CNM353I LISTVAR : 'APPLID' = "APPLIDQ 

SAY "CNM353I LISTVAR : 'OPID' = H OPID() 

SAY "CNM353I LISTVAR : «LU" = "LU() 

SAY "CMM353.I LISTVAR : 'TASK' = "TASKQ 

SAY "CNM353I LISTVAR : 'DATE' = "DATE(USA) 

SAY "CNM353I LISTVAR : 'TIME' = H SUBSTR(TIME(),1,5) 

SAY n CNM353 I LISTVAR : 'NCCFCNT' = "NCCFCNT 

SAY "CNM353I LISTVAR : 'HCOPY' = "HCOPYQ 

IF VTAM() = " THEN /* IS VTAM ACTIVE ? */ 

SAY 'CNM386I LISTVAR : VTAM IS NOT ACTIVE AT THIS TIME' 

END /* OF THE LIST VARIABLES */ 

END /* OF SELECT */ 

RETURN /* RETURN TO CALLER */ 

Figure 127. LISTVAR Example-REXX 



Appendix C. Comparison of REXX and NetView Command List Language 197 



BROWSE Example— NetView Command List Language 



CLIST 
&C0NTR0L ERR 

* SEE THE NETVIEW OPERATIONS MANUAL AND/OR ENTER HELP CLISTNAME 

* FOR A DESCRIPTION OF FUNCTION AND SYNTAX FOR THIS CLIST. 
*********************************************************************** 

* (C) COPYRIGHT IBM CORP. 1986, 1988 * 

* * 

* LAST CHANGE: 03/31/88 15:58:51 SSI=60981558 * 

* * 

* IEBCOPY SELECT MEMBER* ((CNME5O01, BROWS E,R)) * 

* * 

* CNME5001 CHANGED ACTIVITY: * 

* CHANGE CODE DATE DESCRIPTION * 

* , , , , ; _. * 

* $P1=P053950,NV1R3, 880331, MTS: JUST EXIT IF INVALID RETURN CODE * 

* * 

************************************************************** 
************************************************************************ 

* IF FIRST PARM IS A ? THEN GOTO HELP. OTHERWISE DISPLAY A 

* SCREEN TO THE USER IN BROWSE MODE. 
&IF .&1 EQ .? &THEN &GOTO -HELP 

&IF &PARMCNT NE 1 &THEN &GOTO -HELP 

* IF THE PARM IS NETLOGN THEN BROWSE THE NETLOG 
&IF .&1 EQ .NETLOGA &THEN &GOTO -LOG 

&IF .&1 EQ .NETLOGI &THEN &GOTO -LOG 

&IF .&1 EQ .NETLOGS &THEN &GOTO -LOG 

&IF .&1 EQ .NETLOGP &THEN &GOTO -LOG 

VIEW 1 &1 

&VIEWRC « &RETCODE 

&IF &VIEWRC EQ &THEN &EXIT &VIEWRC 

&IF &VIEWRC EQ 4 &THEN &GOTO -SCODE 

&IF &VIEWRC EQ 8 &THEN &GOTG -SCODE 

&IF &VIEWRC EQ 12 &THEN &G0TO -SCODE 

&IF &VIEWRC EQ 16 &THEN &G0TO -SCODE 

&IF &VIEWRC EQ 24 &THEN &GOTO -SCODE 

&IF &VIEWRC EQ 28 &THEN &GOTO -SCODE 

&IF &VIEWRC EQ 32 &THEN &GOTO -SCODE 

&IF &VIEWRC EQ 36 &THEN &GOTO -SCODE 

&EXIT 

-SCODE 

SHOWCODE &VIEWRC &1 

&EXIT &VIEWRC 

-LOG 

STATMON &1 

&EXIT 

-HELP 

HELP BROWSE 

&EXIT 

Figure 128. BROWSE Example— NetView Command List Language 
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BROWSE Example-REXX 



i y***********************************^ 

I/* */ 

i /* THE BROWSE EXAMPLE WRITTEN IN REXX */ 

U* V 



t IF (MSGVAR(1)= , ? , ) 


» 




/* HELP REQUESTED OR 


V 


r (MSGVAR(2)-=") 


» 


/* 2 OR MORE PARMS OR 


*/ 


1 (MSGVAR(l) = ") THEN 


/* NO PARMS ENTERED 


V 


1 'HELP BROWSE' 


/* GO ISSUE GET HELP 


V 


: ELSE 






IF MSGVAR(l)='NETLOGA' 


> 


/* ACTIVE OR 


*/ 


\ MSGVARUh'NETLOGP' 


$ 


/* PRIMARY OR 


*/ 


I MSGVAR(l)='NETLOGS' 


» 


/* SECONDARY OR 


*/ 


[■. MSGVAR(l)=«NETLOGI' THEN 


/* INACTIVE 


*/ 


1 'STATMON 'MSGVAR(l) 


/* GO USE STATMON BROWSE 


V 


I ELSE 






I DO 






f 'VIEW 1 'MSGVAR(l) 


/* GO VIEW THE MEMBER 


V 


i IF RC-=Q THEN 


/* BAD RC? 


*/ 


f 'SHOWCODE * RC MSGVAR(l) 


/* ISSUE SHOWCODE 


V 


t. END 






!, RETURN 











Figure 129. BROWSE Example-REXX 
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ACTLU Example— NetView Command List Languge 



ACTLU CLIST 

&C0NTR0L ERR 
***************************************************** 

* ACTLU COMMAND LIST - NETVIEW COMMAND LIST LANGUAGE VERSION * 

* • ■ . *. : ; 

* FUNCTION : TO ACTIVATE A VTAM NODE. * 

* INPUT : 1 PARAMETER, THE NAME OF THE NODE. * 

************************************************************************ 

&IF .&! = . &THEN &GOTO -NULLPARM 

&NODE = &I 

-WAIT 

&WAIT SUPPRESS 

&WAIT 'V NET,ACT,ID=&NODE' *30=-TIMEOUT + 

*ERROR=-ERROR + 

IST061I=-IST061 + 

IST093I=-IST093 
-ERROR 

&WRITE ERROR PROCESSING ACTIVATE COMMAND 
&EXIT 
-TIMEOUT 

&WRITE NO RESPONSE TO ACTLU CLIST FOR &NODE 
&EXIT 
-IST061 

&WRITE ==> LU UNKNOWN TO YOUR VTAM <==* 
&EXIT 
-IST093 

&WRITE => TERMINAL &1 NOW &2 <== 
&EXIT 
-NULLPARM 

&WRITE PLEASE ENTER "GO NODENAME" OR "GO STOP" TO CONTINUE 
&PAUSE VARS &P1 
&IF &P1 = 'STOP' &THEN &EXIT 
&NODE = &P1 
&GOT0 -WAIT 

Figure 130. ACTLU Example— NetView Command List Language 
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ACTLU Example-REXX 



'OR "60 STOP" TO CONTINUE' 


/*< 


PARSE PULL NODE 


/* 1 


END 


. /* 


ELSE 


/*! 


NODE * MSGVAR(l) 


/*< 




/* 


IF NODE-^'STOP' THEN 


/* I 


DO 


/*! 


'TRAP AND SUPPRESS ONLY MESSAGES 


; 1ST 


'V NET, ACT, ID=' NODE 


/*'■ 


IF RC=0 THEN 


/*' 


DO 


/*' 



t/* ACTLU COMMAND LIST - REXX VERSION */ 

If* FUNCTION : TO ACTIVATE A VTAM NODE. */ 

1 7* INPUT : 1. PARAMETER, THE NAME OF THE NODE. */ 

1 IF MSGVAR(l) = • ' THEN /* NO FIRST PARAMETER ? */ 

L DO /* THEN ISSUE REQUEST */ 

I SAY 'PLEASE ENTER "GO NODENAME"',/* REQUEST NODENAME FROM USER */ 

OR, ALLOW USER TO STOP CLIST */ 

NODE = NODENAME OR STOP */ 

THEN ISSUE REQUEST */ 

FIRST PARAMETER EXISTS */ 

ASSUME IT IS A NODE NAME */ 

IF NODE='STOP' CLIST ENDS */ 

DID USER CHOOSE TO STOP ? */ 

PROCESS NODENAME */ 

/* TRAP ALL VTAM MSGS */ 

ISSUE VTAM ACTIVATE FOR NODE */ 

VALID NODE NAME ? */ 

YES, RETURN CODE =0 */ 

'WAIT 30 SECONDS FOR MESSAGES' /* WAIT FOR 30 SECONDS */ 

IF EVENT()= , M' THEN /* OUT OF WAIT - IS THERE A MSG? */ 

DO /* PROCESS TRAPPED MESSAGE */ 

'MSGREAD' /* READ IN 1ST MESSAGE */ 

DO WHILE (RC=0) /* IF RC-=0 THEN NO MORE MSGS */ 

SELECT /* DETERMINE WHICH MESSAGE HIT */ 

h WHEN (MSGID() = 'ISTOeil') /* NODE NOT FOUND */ 

?■ THEN SAY '==> LU UNKNOWN ', /* INFORM USER */ 

'TO YOUR VTAM <=' 

WHEN (MSGIDQ = 'IST093I*) /* NODE NOW ACTIVE */ 

i THEN SAY '=> TERMINAL ', /* INFORM USER */ 

MSGVAR(l)' NOW ', 

MSGVAR(2) '<==' 

OTHERWISE /* IGNORE THE VTAM MESSAGE */ 

•WAIT CONTINUE* /* CONTINUE WAITING */ 

END /* OF SELECT FOR IST961I/IST093I */ 

•MSGREAD' /* READ IN THE NEXT MESSAGE */ 

END /* 00 WHILE RC=0, LOOP BACK */ 

I END /* PROCESS TRAPPED MESSAGE DO */ 

/* OUT OF DO WHILE, CHECK FOR 

ERROR OR TIMEOUT EVENTS */ 

i : SELECT /* CHECK RESULT OF THE WAIT */ 

I WHEN (EVENT()='E') THEN /* ERROR ENCOUNTERED ? */ 

I. SAY 'ERROR PROCESSING ', /* INFORM USER */ 

'ACTIVATE COMMAND' 

f WHEN (EVENT ()»'. TV) THEN /* WAIT TIMEOUT ENCOUNTERED ? */ 

I SAY 'NO RESPONSE TO ', /* INFORM USER */ 

I- 'ACTLU CLIST FOR 'NODE 

OTHERWISE /* NO-OP */ 

END /* OF SELECT FOR ERROR/TIMEOUT */ 

END /* IF RC=0 (VALID NODENAME) */ 

I END /* IF NODE-='STOP' PROCESSING */ 

Figure 131. ACTLU Example-REXX 
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GETCG Example— NetView Command List Language 



GETCG CLIST 

&C0NTR0L ERR 
******************************************************* 

* GETCG COMMAND LIST - NETVIEW COMMAND LIST LANGUAGE VERSION * 

* * 

* GETCG COMMAND LIST GETS THE VALUE OF A COMMON GLOBAL * 

* VARIABLE AND DISPLAYS IT TO THE REQUESTING TASK * 

**************************************************************** 

&CGL0BAL &1 

MESSAGE 3091 GETCG COMMON GLOBAL VARIABLE &1 HAS VALUE &&1 

&EXIT 

Figure 132. GETCG Example— NetView Command List Language 



GETCG Example-REXX 



/A***************************************************************/ 

/* GETCG COMMAND LIST - REXX VERSION */ 

/* V 

/* GETCG COMMAND LIST GETS THE VALUE OF A COMMON GLOBAL */ 

/* VARIABLE AND DISPLAYS IT TO THE REQUESTING TASK */ 

/****************************************************************/ 

TRACE E 
GLOBALV GETC MSGVAR(l) 

'MESSAGE 3091 GETCG COMMON GLOBAL VARIABLE' MSGVAR(l) » 
'HAS VALUE ' VALUE(MSGVAR(1)) 

EXIT 

Figure 133. GETCG Example-REXX 
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PPTUPDAT Example— NetView Command List Language 



r 

" PPTUPDAT CLIST 

' &C0NTR0L ERR 

; *******************************************************************^ 

■ * THIS COMMAND LIST SETS ANY COMMON GLOBAL VARIABLE ON THE PPT. 
I * USE THE EXCMD COMMAND TO RUN IT ON THE PPT. 

* EXAMPLE: EXCMD PPT PPTUPDAT AAAAAAAA BBBBBBBB 

; * WHERE AAAAAAAA IS THE NAME OF THE COMMON GLOBAL VARIABLE. 

* WHERE BBBBBBBB IS THE VALUE FOR THE COMMON GLOBAL VARIABLE 

************************************************************** 

; &CGLOBAL &1 
&IF .&TASK NE .PPT &THEN &GOTO -ERROR 
&&1 = &2 

MESSAGE 3091 PPTUPDAT COMMON GLOBAL VARIABLE UPDATE COMPLETE 
&EXIT 
-ERROR 

MESSAGE 3091 PPTUPDAT CANNOT UPDATE COMMON GLOBAL VARIABLES + 
FROM NON-PPT TASK 
&EXIT 

Figure 134. PPTUPDAT Example— NetView Command List Language 



PPTUPDAT Example-REXX 



/•••♦•••A*************************************************************/ 

/* THIS COMMAND LIST SETS ANY COMMON GLOBAL VARIABLE ON THE PPT. */ 

/* USE THE EXCMD COMMAND TO RUN IT ON THE PPT. */ 

/* EXAMPLE: EXCMD PPT PPTUPDAT AAAAAAAA BBBBBBBB */ 

/* WHERE AAAAAAAA IS THE NAME OF THE COMMON GLOBAL VARIABLE. */ 

/* WHERE BBBBBBBB...... IS THE VALUE FOR THE COMMON GLOBAL VARIABLE */ 

/•••A*****************************************************************/ 

TRACE E 

/* IF TASK IS NOT THE PPT, ISSUE AN ERROR MESSAGE TO USER */ 

IF TASK() -= 'PPT' THEN 

'MESSAGE 3091 PPTUPDAT CANNOT UPDATE COMMON GLOBAL VARIABLES ', 
'FROM NON-PPT TASK' 
r ELSE 

DO /* TASK IS PPT */ 

INTERPRET VALUE (MSGVAR(l)) '=' MSGVAR(2) /* BUILD &&1 = &2 CMD */ 

GLOBALV PUTC MSGVAR(l) /* PUT COMMON GLOBAL VAR*/ 

'MESSAGE 3091 PPTUPDRX COMMON GLOBAL VARIABLE UPDATE COMPLETE' 

l END /* TASK IS PPT */ 

EXIT 

Figure 135. PPTUPDAT Example-REXX 
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ACTAPPLS Example— NetView Command List Language 



CLIST 

&C0NTR0L ERR 

***************************************************************** 

* * 

* ACTAPPLS - NETVIEW COMMAND LIST LANGUAGE VERSION * 

* * 

* DISPLAY ONLY THE ACTIVE APPLS * 

* * 
******************************************************************** 

* WRITE THE HEADER 
&WRITE ACTIVE APPLICATIONS: 
&WRITE ================= 

* WAIT ON THE DISPLAY COMMAND 
&WAIT CONTWAIT SUPPRESS 

&WAIT 'D NET,APPLS',IST350I=-FIRST,*=-ALLELSE 

* ALL NON- INFORMATIONAL MESSAGES GO HERE 
-ALLELSE 

&WAIT CONTINUE 

* THE MULTILINE WTO WITH THE APPL INFORMATION COMES HERE 
-FIRST 

* DETERMINE THE NUMBER OF LINES 
GETMSIZE NUMLINES 

♦INITIALIZE LINE NUMBER COUNTER, AND TOTAL ACTIVE APPLS 
&I = 
&TOTALACT = 

* TOP OF THE MLWTO LOOP 
-LOOP 

* SET NUMBER OF ACTIVE APPLS FOUND ON THIS LINE TO 
&NUMACT = 

* IF WE HAVE PARSED ALL THE LINES WE ARE DONE 
&IF &NUMLINES = &I &THEN &GOTO -ALLDONE 

* DETERMINE THE NUMBER OF LINES IN THE MLWTO 
GETMLINE LINE &I 

* PARSE OUT THE LINE, Al A2 A3 ARE APPL NAMES, SI S2 S3 ARE STATUS 
PARSEL2R LINE MSG Al SI A2 S2 A3 S3 

* IF THERE IS NO STATUS, DONE WITH THIS LINE 
&IF &S1. = . &THEN &GOTO -NOCHECK 

* CHECK TO SEE IF THE STATUS OF APPL 1 IS ACTIVE 
&IF &S1 = 'ACTIV &THEN &GOTO -A1ACT 

&IF &S1 = ' ACTIV &THEN &GOTO -A1ACT 
&IF &S1 = ' ACTIV &THEN &GOTO -A1ACT 

* APPL1 IS NOT ACTIVE, BUNK IT OUT 
&S1 = • ' 

&A1 = " 

* CHECK THE NEXT APPL 
&GOTO -CHECKA2 

* THIS APPL IS ACTIVE 
-A1ACT 

* BUMP NUMBER ACTIVE COUNT 
&NUMACT = &NUMACT + 1 

Figure 136 (Part 1 of 2). ACTAPPLS Example— NetView Command List Language 
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-CHECKA2 

* CHECK TO SEE IF THE STATUS OF APPL 2 IS ACTIVE 
&IF &S2. = . &THEN &GOTO -CHECKA3 

&IF &S2 = 'ACTIV &THEN &GOTO -A2ACT 
&IF &S2 = ' ACTIV &THEN &GOTO -A2ACT 
&IF &S2 = ' ACTIV SJHEN &GOTO -A2ACT 

* APPL2 IS NOT ACTIVE, BLANK IT OUT 

652 - ' ' 
&A2 = " 
&GOTO -CHECKA3 

* THIS APPL IS ACTIVE 
-A2ACT 

* BUMP NUMBER ACTIVE COUNT 
&NUMACT = &NUMACT + 1 
-CHECKA3 

&IF &S3. = . SJHEN &GOTO -NOCHECK 
&IF &S3 = 'ACTIV &THEN &GOTO -A3ACT 
&IF &S3 = ' ACTIV SJHEN &GOTO -A3ACT 
&IF &S3 = ' ACTIV SJHEN &GOTO -A3ACT 

* APPL3 IS NOT ACTIVE, BLANK IT OUT 

653 = ' ' 
&A3 = " 
&GOTO -NOCHECK 

* THIS APPL IS ACTIVE 
-A3ACT 

* BUMP NUMBER ACTIVE COUNT 
&NUMACT = &NUMACT +1 
-NOCHECK 

* ENABLE THE DISPLAYING 
&WAIT CONTWAIT DISPLAY 

* * ANY ACTIVE ON THIS LINE ? 
&IF &NUMACT = SJHEN &GOTO -NOWRITE 

* DISPLAY THE ACTIVE APPLICATIONS 
&WRITE &A1 &A2 &A3 

-NOWRITE 

* BUMP THE LINE COUNTER 
&I = &I + 1 

* BUMP THE TOTAL ACTIVE COUNTER 
SJOTALACT = SJOTALACT + &NUMACT 

* GO PROCESS THE NEXT LINE 
&GOTO -LOOP 

* THE PARSING IS DONE 
-ALLDONE 

* DISPLAY THE NUMBER OF ACTIVE APPLICATIONS 
&WRITE NUMBER OF APPLICATIONS ACTIVE: &TOTALACT 
GO 

S.EXIT 

Figure 136 (Part 2 of 2). ACTAPPLS Example— NetView Command List Language 
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ACTAPPLS Example-REXX 



7 

7 

V 

V 

V 

V 

V 

7 
7 

7 
V 

v. 

7 



/* 
/* 
/*■■ 
/* 
/* 
'/* 
/* 
/* 
/* 

7* 
7* 

7* 

/•••••••♦••A******************************************************* 

TRACE E 

/* WRITE THE HEADER */ 

'CLEAR 1 

SAY • ACTIVE APPLICATIONS: 1 



APPLRX : DISPLAY ONLY THE ACTIVE APPLS 

THIS COMMAND LIST PROCESSES THE FOLLOWING VTAM MESSAGES 

IST350I DISPLAY TYPE = APPL MAJ NODES/NAMES 

IST089I TYPE=APPL SEGMENT , ACTIV 

IST360I APPLICATIONS: 

IST080I APPL1 STATUS1 APPL2 STATUS2 APPL3 STATUS3 

ALL ARE IGNORED, EXCEPT FOR ISTQ80I WHERE THE APPLS & 
THEIR RESPECTIVE STATUS ARE DISPLAYED (IF ACTIVE) 



/* 
/*■ 

7* 

/*: 
/*■ 

7* 



CLEAR THE SCREEN */ 



1ST HEADER MSG 
2ND HEADER MSG 
TRAP HEADER & 
DATA MESSAGES 
ISSUE D NET CMD 



•TRAP SUPPRESS ONLY MESSAGES IST997I IST350I' 

'D NET,APPLS« 

'WAIT 5 SECONDS FOR MESSAGES' 

'MSGREAD' 

DO WHILE (MSGIDQ — 'IST350r)-' 

•WAIT CONTINUE' 

'MSGREAD 1 
END 
/* AT THIS POINT AN IST350I MLWTO BUFFER MSG HAS BEEN RECEIVED 



7 

7 
7 
7 
7 

/* WAIT FOR RESP. */ 
/* READ 1ST MESSAGE */ 

IST350I ? 

NO- CONT. WAIT 

READ NEXT MSG 

END IST350I 



/* 
/* 
/* 
/* 



NUMACT = G 
OUTLINE- ' ' 
GETMSIZE NUMLINES 

/* 

DO 1=1 TO NUMLINES 

'GETMLINE LINE' I 
•PARSEL2R LINE', 

'MSG', 

•Al SI',. 

*A2 S2', 

'A3 S3' 
IF MSG -'ISTQSOr 



7* 
/* 
/* 

/* 



INIT. TOTAL CNTR 
CLEAR OUTLINE 
GET NUM LINES 
IN MLWTO BUFFER 



THEN 



IF LEFT(S1,8)= 'ACTIV THEN 

CALL ADDACT(Al) 
IF LEFT(S2,8)= 'ACTIV THEN 

CALL ADDACT(A2) 
IF LEFT(S3,8)= 'ACTIV THEN 
CALL ADDACT(A3) 
END 
END 



/* LOOP THRU BUFFER 
/* GET MLWTO LINE 
PARSE LINE INTO 
MESSAGE ID 
1ST APPL/STATUS 
2ND APPL/STATUS 
3RD APPL/STATUS 
IST080I? 
YES — 

APPL1 ACTIVE ? 
ADD APPL Al 
APPL2 ACTIVE ? 
ADD APPL A2 
APPL3 ACTIVE ? 



/* 
/* 
I* 
I* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/*■ 



/* ADD APPL A3 



/* 
/* 



IST080I PROCESS 



V 
V 
V 

*/■ 

7 
V 

*/ 

V 

*/ 

V 

*/ 
*/ 

V 
V 
V 
V 

*/ 

*/ 

V 
7 
V 
*/■ 
V. 
V 
V 
7 



LOOP THRU BUFFER */ 



Figure 137 (Part 1 of 2). ACTAPPLS Example— REXX 
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J IF NUMACT//3-.-0 THEN /* NEED ANOTHER SAY?*/ 

! SAY OUTLINE /* PUT LINE OUT */ 

f SAY « >== END OF DISPLAY ===<' /* EOD MESSAGE */ 

i SAY 'NUMBER OF APPLICATIONS ACTIVE: ' NUMACT /* STATUS MESSAGE */. 

• EXIT 

I ADDACT: 

i /* ADD THE APPL NAME GIVEN TO THE OUTPUT LIST. IF THERE ARE EXACTLY 

* FIVE ENTRIES, THEN PUT OUT THE LINE */ 
; ARG APPL 

OUTLINE=OUTLINE7||' ' | |LEFT(APPL,8) 
NUMACT=NUMACT+1 
IF NUMACT//3=0 THEN 
DO 

SAY OUTLINE 
OUTLINE^' • 
END 
RETURN 

Figure 137 (Part 2 of 2). ACTAPPLS Example— REXX 
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Appendix D. Converting Command Lists Written in the 
NetView Command List Language to REXX 



The NetView program provides a sample rexx exec that you can use to convert 
command lists written in the NetView command list language to rexx. The exec is 
shipped as NetView sample cnmssool You can rename the sample, but this section 
assumes you use the cnmssooi name. 

You can use cnmssooi to convert a command list written in the NetView command 
list language list to a bilingual command list or a REXX-only command list. The 
bilingual command list contains both the existing NetView command list language 
version of the command list and the new rexx version. During the conversion, 
cnmssooi reads each line of the NetView command list language version of the 
command list and writes the equivalent line in the rexx version. The records in the 
bilingual command list and the RExx-only command list are up to 80 characters in 
length and do not have sequence numbers. 

There are some NetView command list language conditions that cnmssooi cannot 
convert and there are other conditions that might not be converted correctly. When 
these conditions occur, cnmssooi writes messages to a warning file to notify you of 
any conversion problems. See "Conditions CNMS8001 Cannot Convert" on 
page 213 and "Conditions CNMS8001 Might Not Convert Correctly" on page 213 
for information on conversion restrictions. 

cnmssooi can be executed on the following operating systems: 

• VM 

• tso/e running under mvs/xa. 

Notes: 

1. cnmssooi cannot run under the NetView environment. 

2. To run cnmssooi, the rexx interpreter must be installed. 
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Executing CNMS8001 Command List on TSO/E 



You can execute cnmssooi on a tso/e system running under mvs/xa in one of two 
ways. The method you use depends on whether your syslcnmsamp data set is allo- 
cated to the sysproc or sysexec dd statement for the tso/e session. The cnmssooi 
exec is contained in the syslcnmsamp data set. 

Figure 138 shows the syntax for running cnmssooi if syslcnmsamp is not allocated 
to sysproc or sysexec. Figure 139 on page 211 shows the syntax for running 
CNMS8001 if syslcnmsamp is allocated to sysproc or SYSEXEC 



EXEC , SYS1.CNMSAMP(CNMS8001>' ^'l" 'inputds" 
"outputds* ' ' 'warnds 1 » KNOSUPPK SUPPI ' 

Figure 138. Syntax to Run CNMS8001 when SYSLCNMSAMP is not Allocated to SYSPROC 
or SYSEXEC 

? 

indicates that the cnmssooi help screens should be displayed. 

inputds 

specifies the mvs data set name of the NetView command list language 
command list being converted. 

outputds 

specifies the mvs data set name that you want to contain the converted 
command list. 

warnds 

specifies the mvs data set name that you want to contain the warning file 
created during the conversion. 

(NOSUPPK SUPP 

(NOSUPP this optional parameter specifies that you want outputds to be a 
bilingual command list. If you do not specify (nosupp or (Supp, 
(nosupp is the default. 

(SUPP this optional parameter specifies that you want outputds to be a 
rexx only command list. 



Notes: 



The string of inputds, outputds, warnds, and optionally the (nosupp or (supp 
parameter are enclosed in a set of single quotes. Within that set of single 
quotes, each individual data set name is enclosed within two more sets of 
single quotes. If a data set name is not enclosed in two sets of single quotes, 
the high level qualifier for that data set name defaults to the user id. 

For example, if the following command was entered by operl 

EXEC 'SYS1.CNMSAMP(CNMS80O1) ' ' ' 'USER.CLIST(CLISTl) ' ' 
' 'USER.CLISTl(REXXl) ' ' CLIST(WARNl) ' 

cnmssooi would convert the NetView command list language command list in 
user.clist(CLISTi) to a bilingual command list and place the bilingual command 
list in user.clist(REXXI). Any warning or error messages would be placed in 
operlclist(warni). The high level identifier for clist(warni) defaults tooPERi, 
because the data set name is not enclosed in two sets of single quotes. 
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2. The members for the converted command list and the warning file cannot be in 
the same data set. The data sets for the converted command list and the 
warning file cannot be allocated by another job (for example, if NetView is 
running you cannot put the output into the allocated NetView command list data 
sets). 

Figure 139 shows the syntax for running cnmssooi if sysi.cnmsamp is allocated to 

SYSPROC Or SYSEXEC. 



CNMS8001 7\ l inputds l Outputds' *warnds' r<NOSUPPI (SUPP1 

Figure 139. Syntax to Run CNMS8001 when SYSLCNMSAMP is Allocated to SYSPROC or 
SYSEXEC 

? 

indicates that the cnmssooi help screens should be displayed. 

inputds 

specifies the mvs data set name of the NetView command list language 
command list being converted. 

outputds 

specifies the mvs data set name that you want to contain the converted 
command list. 

warnds 

specifies the mvs data set name of the warning file created during the conver- 
sion. 

(NOSUPPK SUPP 

(NOSUPP this optional parameter specifies that you want outputds to be a 
bilingual command list. If you do not specify (nosupp or (SUPP, 
(NOSupp is the default. 

(SUPP this optional parameter specifies that you want outputds to be a 
rexx only command list. 

Notes: 

1. Each individual data set name is enclosed within a set of single quotes. If a 
data set name is not enclosed in single quotes, the high level qualifier for that 
data set name defaults to the user id. 

For example, if the following command was entered by operi: 

CNMS8001 'USER.CLIST(CLISTl)' 'USER.CLIST(REXXl) ' CLISTl(WARNl) (SUPP 

cnmssooi would convert the NetView command list language command list in 
user.clist(CUSTI) to a rexx command list and place the rexx command list in 
user.clist(rexxi). Any warning or error messages would be placed in 
oper-i.clist(warni). The high level identifier for clist(warni) defaults to operi, 
because the data set name is not enclosed in single quotes. 

2. The members for the converted command list and the warning file cannot be in 
the same data set. The data sets for the converted command list and the 
warning file cannot be allocated by another job (for example, if NetView is 
running you cannot put the output into the allocated NetView command list data 
sets). 
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Executing CNMS8001 Command List on VM Operating System 

Figure 140 shows the syntax of the statement used to run the cnmssooi command 
list on the vm operating system. 



CNMS8001 ?\inputfn [inputft [inputfmj] 
[outputfn outputft outputfm 
warnfn wamft warnfm"} 
KNOSUPPK SUPP1 

Figure 140. Syntax to Run CNMS8001 Command List on VM Operating System 

? 

indicates that the cnmssooi help screens should be displayed. 

inputfn 

specifies the vm file name of the NetView command list language command list 
being converted. 

inputft 

specifies the vm file type of the NetView command list language command list 
being converted. If you do not code a file type or you code an asterisk (*), the 
file type defaults to clist. 

inputfm 

specifies the vm file mode of the NetView command list language command list 
being converted. If you do not code a file mode or you code an asterisk (*), the 
file mode defaults Jo a. 

Note: If you want to change any of the default file specifications for the output file 
or the warning file, you must specify a value or asterisk (*) for each of the following 
six operands: 

outputfn 

specifies the vm file name of the command list created during the conversion. 
If you use the default file specifications for the output and warning files or you 
code an asterisk (*) for this parameter, the file name defaults to the name spec- 
ified in inputfn. 

outputft 

specifies the vm file type of the command list created during the conversion. If 
you use the default file specifications for the output and warning files or you 
code an asterisk (*) for this parameter, the file type defaults to exec. 

outputfm 

specifies the vm file mode of the command list created during the conversion. 
If you use the default file specifications for the output and warning files or you 
code an asterisk (*) for this parameter, the file mode defaults to a. 

warnfn 

specifies the vm file name of the warning file created during the conversion. If 
you use the default file specifications for the output and warning files or you 
code an asterisk (*) for this parameter, the file name defaults to the name spec- 
ified in inputfn. 

wamft 

specifies the vm file type of the warning file created during the conversion. If 
you use the default file specifications for the output and warning files or you 
code an asterisk (*) for this parameter, the file type defaults to warning. 
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warnfm 

specifies the vm file mode of the warning file created during the conversion. If 
you use the default file specifications for the output and warning files or you 
code an asterisk (*) for this parameter, the file mode defaults to a. 

(NOSUPPK SUPP 

(NOSUPP this optional parameter specifies that you want outputfn to be a 
bilingual command list. If you do not specify (nosupp or (supp, 
(NOSUpp is the default. 

(SUPP this optional parameter specifies that you want outputfn to be a 
rexx only command list. 



Conditions CNMS8001 Cannot Convert 



There are some conditions that cnmssooi cannot convert. When these conditions 
occur, the line in the NetView command list language command list is not con- 
verted. Each unconverted line is highlighted in the output file with three exclama- 
tion marks (!!!) at the beginning and the end of the line. A message containing the 
output file name and the line number of each line that could not be converted is 
written in the warning file. 

The conditions that cannot be converted are: 

• &begwrite control statements having a label that is a variable. 

• NetView command list language variables that cnmssooi converts to rexx func- 
tions and that are objects of assignment statements. 



Conditions CNMS8001 Might Not Convert Correctly 



There are some conditions that cnmssooi might not be able to convert correctly. 
When these conditions occur, messages are written in the warning file that instruct 
you to check the output file to verify that the conversion was done correctly. In 
most cases, the messages list the line numbers of the lines that might not have 
been converted correctly. 

Some of the conditions that might not convert correctly are: 

• &tglobal and &cglobal commands 

A list of the variables specified on &cglobal or &tglobal commands is provided 
in the warning file. Check the rexx portion of the output file to verify that these 
variables are assigned correctly. 

• &wait commands 

The &wait commands are converted, and messages are written to the warning 
file to inform you that various &wait commands were converted. Check the 
rexx portion of the output file to verify that the new trap, wait, and msgread 
commands can perform the desired operations. 

• Parentheses and logical operators that are in a string. 

These lines are converted, and messages are written to the warning file that 
contain the line numbers of the converted lines. Check the rexx portion of the 
output file to ensure that the parentheses and logical operators were converted 
correctly. 
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• Strings that contain a single quote followed by the letter X 

These lines are converted, but, in some cases, the rexx interpreter perceives 
this condition as hexadecimal. Messages containing the line numbers of any 
lines having strings that contain a single quote followed by the letter X are 
written in the warning file. Check the rexx portion of the output file to verify 
that these strings were not interpreted as hexadecimal. 

• Lines that contain an odd number of quotes in a string 

These lines are converted, but quote placement may not be correct. Messages 
are written to the warning file that list the line number of each line containing 
an odd number of quotes. Check the rexx portion of the output file to verify that 
the quotes were placed correctly. 

• &A&B type variables 

CNMS8001 converts these variables. However, if the value that is put into the &b 
portion of the variable when the command list is run contains invalid rexx 
symbols, the rexx command list created by cnmssooi will not execute. 

Another condition that might cause problems when you run a converted command 
list is the default initial value of variables. No messages are written to the warning 
file for this condition. If a rexx variable is not assigned an initial value, its value 
defaults to the name of the variable. If a NetView command list language variable 
is not assigned an initial value, its value defaults to null. Therefore, if the logic of a 
command list written in the NetView command list language depends on a variable 
having a default initial value of null, the rexx version of the command list created 
by cnmssooi will not run correctly. 

Also, cnmssooi assumes that the converted command list will always be called as a 
command and not as a subroutine or function. Therefore, the NetView command 
list language &1 - &31 variables are always converted to the rexx msgvar(1) - 
msgvr(31) functions and not arg(1) - arg(31). 



Improving the Performance of Converted Command Lists 

When the cnmssooi conversion tool converts a command list, it does not attempt to 
optimize the performance of the rexx command list it creates, rexx has many more 
features and functions than the NetView command list language. Because cnmssooi 
only converts each line in the NetView command list language command list to its 
rexx equivalent, you can still enhance the performance of the rexx command list by 
manually adding additional rexx features and functions. After fixing those condi- 
tions that cnmssooi could not convert or that might not have been converted cor- 
rectly, go back and review the rexx command list to determine if its performance 
could be improved. 

Some of the things you can do to improve the performance of a converted 
command list are: 

• Improve the program structure by using rexx instructions such as call, do, if, 
and select. 

• Use rexx arithmetic operators that are not available in the NetView command 
list language. For example, multiply (*) and divide (/). 

• Use rexx functions that have no NetView command list language equivalent. 
For example, reverseo, poso, datatypeo, wordso, and many others. 
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• Reduce the use of the rexx functions provided by NetView. Using these func- 
tions is inefficient in terms of performance. If the same function, provided by 
NetView, is used several times in the command list without a change in value, 
use the function once to set a local variable to the value of the function. After 
setting the rexx function provided by NetView to a local variable, use the local 
variable in place of the function. If the value of the function changes during 
execution of the command list, you need to use the function each time to 
access its current value. 

For complete information about the features and functions of rexx, see REXX Ref- 
erence or REXX User's Guide. 



Example of a Converted Command List 



The command list in Figure 141 on page 216 is an example of a bilingual 
command list created using cnmssool The NetView command list language portion 
of the command list was used as input to cnmssool 
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/* CLIST TO BE CONVERTED 

CLIST 
&CONTROL ERR 

* SEE THE NETVIEW OPERATION MANUAL AND/OR ENTER HELP CLISTNAME 

* FOR A DESCRIPTION OF FUNCTION AND SYNTAX FOR THIS CLIST. 
************************************************************ 

* (C) COPYRIGHT IBM CORP. 1986, 1987 * 

* . * 

* LAST CHANGE: 04/08/86 15:41:52 SSI=60981541 * 

* .-•'■■*•' 

* IEBCOPY SELECT MEMBER=((CNME1O07,LSESS,R)) * 

* * 

* OUTPUTS: * 

* ONE OF: . ■ * 

* LISTSESS * 

* LISTSESS OPCTL * 

* LISTSESS FLSCN * 

* LISTSESS APPLID=&2 * 

* LISTSESS SRCLU=&2 * 

* '•■■*■ 

* CNME1O07 CHANGED ACTIVITY: * 

* CHANGE CODE DATE DESCRIPTION * 



*********************************************************************** 

&P1 = &1 
&P2 - &2 

&IF .&P1 EQ .? &THEN &GOTO -HELP 

&IF .&P1 EQ . &THEN &GOTO -HELP 

&IF .&P1 EQ .ALL &THEN &GOTO -LALL 

&IF .&P1 EQ .0 &THEN &GOTO -OPCT 

&IF .&P1 EQ .OPCTL &THEN &GOTO -OPCT 

&IF .&P1 EQ .F &THEN &GOTO -FLSC 

&IF .&P1 EQ .FLSCN &THEN &GOTG -FLSC 

&IF .&P1 EQ .A &THEN &GOTO -APPL 

&IF .&P1 EQ .S &THEN &GOTO -SRCL 
* INVALID PARAMETER 
MESSAGE 306E,LSESS,&1 
&EXIT 

Figure 141 (Part 1 of 4). Bilingual Command List Created by CNMS8001 
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I *************************************************************** 

I -LALL 

' * COMMAND ENTERED: LSESS ALL 

l&CONTROL CMD 

| LISTSESS 

f &CONTROL ERR 

l&EXIT 

l ; 

f *********************************************************************** 

f -OPCT 

* COMMAND ENTERED: LSESS OR LSESS OPCTL 
&CONTROL CMD 

LISTSESS OPCTL 
&CONTROL ERR 

&EXIT 

*********************************************************************** 

-FLSC 

* COMMAND ENTERED: LSESS F OR LSESS FLSCN 
&CONTROL CMD 

LISTSESS FLSCN 
&CONTROL ERR 

&EXIT 

*********************************************************************** 

-APPL 

* COMMAND ENTERED: LSESS APPLID (OF FIVE CHARACTERS) 
&IF .11 EQ . &THEN &GOTO -ERROR 

&CONTROL CMD 
LISTSESS APPLID=&P2 
&CONTROL ERR 

&EXIT 

*********************************************************************** 

-SRCL 

* COMMAND ENTERED: LSESS OR LSESS OPCTL 
&IF .&2 EQ . &THEN &60T0 -ERROR 

&CONTROL CMD 
LISTSESS SRCLU=&P2 
&CONTROL ERR 

&EXIT 

*********************************************************************** 

-ERROR 

MESSAGE 330E, LSESS, SECOND 

&EXIT 

*********************************************************************** 

-HELP 

HELP LSESS 
&EXIT 

END OF CLIST */ 
/* REXX CONVERSIONS */ 



Figure 141 (Part 2 of 4). Bilingual Command List Created by CNMS8001 
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/* CLIST */ 
TRACE E 
/* SEE THE NETVIEW OPERATIONS MANUAL AND/OR ENTER HELP CLISTNAME*/ 

/* FOR A DESCRIPTION OF FUNCTION AND SYNTAX FOR THIS CLIST.*/ 

/**************************************^ 

/* (C) COPYRIGHT IBM CORP. 1986, 1987 **/ 

.' . /* **/ 

/*■ LAST CHANGE: 04/08/86 15:41:52 SSI=60981541 **/ 
/* ■ **/ 

/* IEBCOPY SELECT MEMBER=((CNME1O07,LSESS,R)) **/ 

/* **/ 

/* OUTPUTS: **/ 

■/* ONE OF: **/ 

/* LISTSESS **/ 

/* LISTSESS OPCTL **/ 

■■/*■' LISTSESS FLSCN **/ 

/* LISTSESS APPLID=&2 **/ 

/* LISTSESS SRCLU=&2 **/ 

/* ** / 

/* CNME1007 CHANGED ACTIVITY: **/ 

/* CHANGE CODE DATE DESCRIPTION **/ 

/* , . , ** / 

I* **/ 

PI = MSGVAR(l) 
P2 - MSGVAR(2) 

IF VP1 » '.?' THEN SIGNAL HELP 
IF '.'PI = «.• THEN SIGNAL HELP 
IF '.'PI » '.ALL' THEN SIGNAL LALL 
IF '.'PI = '.0' THEN SIGNAL OPCT 
IF '.'PI - '.OPCTL' THEN SIGNAL OPCT 
IF '.'PI » '.F' THEN SIGNAL FLSC 
IF '.'PI = '.FLSCN' THEN SIGNAL FLSC 
IF '.'PI = '.A' THEN SIGNAL APPL 
IF '.'PI = '.S' THEN SIGNAL SRCL 
/* INVALID PARAMETER*/ 
'MESSAGE 306E,LSESS,'MSGVAR(1) 
EXIT 

LALL: 

/* COMMAND ENTERED: LSESS ALL*/ 

TRACE C 

'LISTSESS' 

TRACE E 

EXIT 

Figure 141 (Part 3 of 4). Bilingual Command List Created by CNMS8001 
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I OPCT: 

| /* COMMAND ENTERED: LSESS OR LSESS OPCTL*/ 

I TRACE C 

I 'LISTSESS OPCTL 1 

i TRACE E 

I EXIT 

I. FLSC: 

I /* COMMAND ENTERED: LSESS F OR LSESS FLSCN*/ 

I TRACE C 

I 'LISTSESS FLSCN' 

h TRACE E 

I EXIT 

I y*************************************^ 

l-'APPL: 

I /* COMMAND ENTERED: LSESS APPLID (OF FIVE CHARACTERS)*/ 

| IF '.'MSGVAR(2) « V THEN SIGNAL ERROR 

I TRACE C 

f 'LISTSESS APPLID='P2 

k TRACE E 

I EXIT 

I /*******************************************************•* 

| SRCL: 

I /* COMMAND ENTERED: LSESS OR LSESS OPCTL*/ 

I IF VMSGVAR(2) = '.' THEN SIGNAL ERROR 

| TRACE C 

f 'LISTSESS SRCLU='P2 

f TRACE E 

| EXIT 

t y************************************************************ 

f ERROR: 

| 'MESSAGE 330E, LSESS, SECOND' 

I EXIT 

b- /A********************************************************** 

f HELP: 

I 'HELP LSESS' 

I EXIT 

"i: 

Figure 141 (Part 4 of 4). Bilingual Command List Created by CNMS8001 
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Glossary 



This glossary defines important NCP, NetView, 
NetView/PC, SSP, and VTAM abbreviations and terms. 
It includes information from the IBM Dictionary of Com- 
puting, SC20-1699. Definitions from the American 
National Dictionary for Information Processing are 
identified by an asterisk (*). Definitions from draft pro- 
posals and working papers under development by the 
International Standards Organization, Technical Com- 
mittee 97, Subcommittee 1 are identified by the symbol 
(TC97). Definitions from the CCITT Sixth Plenary 
Assembly Orange Book, Terms and Definitions and 
working documents published by the Consultative Com- 
mittee on International Telegraph and Telephone of the 
International Telecommunication Union, Geneva, 1980 
are preceded by the symbol (CCITT/ITU). Definitions 
from published sections of the ISO Vocabulary of Data 
Processing, developed by the International Standards 
Organization, Technical Committee 97, Subcommittee 1 
and from published sections of the ISO Vocabulary of 
Office Machines, developed by subcommittees of ISO 
Technical Committee 95, are preceded by the symbol 
(ISO). 

For abbreviations, the definition usually consists only of 
the words represented by the letters; for complete defi- 
nitions, see the entries for the words. 

Reference Words Used in the Entries 

The following reference words are used in this 
glossary: 

Deprecated term for. Indicates that the term should 
not be used. It refers to a preferred term, which is 
defined. 

Synonymous with. Appears in the commentary of a 
preferred term and identifies less desirable or less 
specific terms that have the same meaning. 

Synonym for. Appears in the commentary of a less 
desirable or less specific term and identifies the 
preferred term that has the same meaning. 

Contrast with. Refers to a term that has an opposed 
or substantively different meaning. 

See. Refers to multiple-word terms that have the 
same last word. 

See also. Refers to related terms that have similar 
(but not synonymous) meanings. 



ACB name. (1) The name of an ACB macroinstruction. 
(2) A name specified in the ACBNAME parameter of a 
VTAM APPL statement. Contrast with network name. 

accept. For a VTAM application program, to establish 
a session with a logical unit (LU) in response to a CINIT 



request from a system services control point (SSCP). 
The session-initiation request may begin when a ter- 
minal user logs on, a VTAM application program issues 
a macroinstruction, or a VTAM operator issues a 
command. See also acquire (1). 

access method. A technique for moving data between 
main storage and input/output devices. 

accounting exit routine. In VTAM, an optional installa- 
tion exit routine that collects statistics about session 
initiation and termination. 

ACF. Advanced Communications Function. 

ACF/NCP. Advanced Communications Function for the 
Network Control Program. Synonym for NCP. 

ACF/SSP. Advanced Communications Function for the 
System Support Programs. Synonym for SSP. 

ACF/VTAM. Advanced Communications Function for 
the Virtual Telecommunications Access Method. 
Synonym for VTAM. 

acquire. (1) For a VTAM application program, to ini- 
tiate and establish a session with another logical unit 
(LU). The acquire process begins when the application 
program issues a macroinstruction. See also accept. 
(2) To take over resources that were formerly con- 
trolled by an access method in another domain, or to 
resume control of resources that were controlled by 
this domain but released. Contrast with release. See 
also resource takeover. 

activate. To make a resource of a node ready to 
perform the functions for which it was designed. Con- 
trast with deactivate. 

active. (1) The state a resource is in when it has been 
activated and is operational. Contrast with inactive, 
pending, and inoperative.. (2) Pertaining to a major or 
minor node that has been activated by VTAM. Most 
resources are activated as part of VTAM start proc- 
essing or as the result of a VARY ACT command. 



adaptive session pacing. 

session-level pacing. 



Synonym for adaptive 



adaptive session-level pacing. A form of session-level 
pacing in which session components exchange pacing 
windows that may vary in size during the course of a 
session. This allows transmission to adapt dynamically 
to variations in availability and demand of buffers on a 
session by session basis. Session pacing occurs 
within independent stages along the session path 
according to local congestion at the intermediate 
nodes. Synonymous with adaptive session pacing. 
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See pacing, session-level pacing, and virtual route 
pacing. 

Advanced Communications Function (ACF). A group of 
IBM licensed programs (principally VTAM, TCAM, NCP, 
and SSP) that use the concepts of Systems Network 
Architecture (SNA), including distribution of function 
and resource sharing. 

alert. (1) In SNA, a record sent to a system problem 
management focal point to communicate the existence 
of an alert condition. (2) In the NetView program, a 
high priority event that warrants immediate attention. 
This data base record is generated for certain event 
types that are defined by user-constructed filters. 

allocate. A logical unit (LU) 6.2 application program 
interface (API) verb used to assign a session to a con- 
versation for the conversation's use. Contrast with 
deallocate. 

API. Application program interface. 

application program. (1) A program written for or by a 
user that applies to the user's work. (2) A program 
used to connect and communicate with stations in a 
network, enabling users to perform application-oriented 
activities. 

application program interface (API). (1) The formally 
defined programming language interface between an 
IBM system control program or licensed program and 
its user. (2) The interface through which an application 
program interacts with an access method. In VTAM, it 
is the language structure used in control blocks so that 
application programs can reference them and be identi- 
fied to VTAM. 

attaching device. Any device that is physically con- 
nected to a network and can communicate over the 
network. 

authorization exit routine. In VTAM, an optional instal- 
lation exit routine that approves or disapproves 
requests for session initiation. 

authorized receiver. In the NetView program, an 
authorized operator who receives all the unsolicited 
and authorized-receiver messages not assigned to a 
specific operator. 

automatic logon. (1) A process by which VTAM auto- 
matically creates a session-initiation request to estab- 
lish a session between two logical units (LUs). The 
session will be between a designated primary logical 
unit (PLU) and a secondary logical unit (SLU) that is 
neither queued for nor in session with another PLU. 
See also controlling application program and control- 
ling logical unit. (2) In VM, a process by which a 
virtual machine is initiated by other than the user of 
that virtual machine. For example, the primary VM 



operator's virtual machine is activated automatically 
during VM initialization. 

available. In VTAM, pertaining to a logical unit that is 
active, connected, enabled, and not at its session limit. 

BIU segment. In SNA, the portion of a basic informa- 
tion unit (BIU) that is contained within a path informa- 
tion unit (PIU). It consists of either a request/response 
header (RH) followed by all or a portion of a 
request/response unit (RU), or only a portion of an RU. 

blocking of PIUs. In SNA, an optional function of path 
control that combines multiple path information units 
(PIUs) into a single basic transmission unit (BTU). 

boundary function. (1) A capability of a subarea node 
to provide protocol support for attached peripheral 
nodes, such as: (a) interconnecting subarea path 
control and peripheral path control elements, (b) per- 
forming session sequence numbering for low-function 
peripheral nodes, and (c) providing session-level 
pacing support. (2) The component that provides these 
capabilities. See also boundary node, network 
addressable unit (NAU), peripheral path control, 
subarea node, and subarea path control. 

boundary node. (1) A subarea node with boundary 
function. See subarea node (including illustration). 
See also boundary function. (2) The programming 
component that performs FID2 (format identification 
type 2) conversion, channel data link control, pacing, 
and channel or device error recovery procedures for a 
locally attached station. These functions are similar to 
those performed by a network control program for an 
NCP-attached station. 

browse. A way of looking at a file that does not allow 
you to change it. 

buffer. A portion of storage for temporarily holding 
input or output data. 

call. (1) * (ISO) The action of bringing a computer 
program, a routine, or a subroutine into effect, usually 
by specifying the entry conditions and jumping to an 
entry point. (2) To transfer control to a procedure, 
program, routine, or subroutine. (3) The actions nec- 
essary to make a connection between two stations. 
(4) To attempt to contact a user, regardless of whether 
the attempt is successful. 

CALLOUT. The logical channel type on which the data 
terminal equipment (DTE) can send a call, but cannot 
receiveone. 

calling. * (ISO) The process of transmitting selection 
signals in order to establish a connection between data 
stations. 

chain. (1) A group of logically linked records. (2) See 
RU chain. 



224 NetView Customization: Writing Command Lists 



channel-attached. (1) Pertaining to the attachment of 
devices directly by input/output channels to a host 
processor. (2) Pertaining to devices attached to a con- 
trolling unit by cables, rather than by telecommuni- 
cation lines. Contrast with link-attached. Synonymous 
with local. 

character-coded. Synonym for unformatted. 

CICS. Customer Information Control System. 

CLIST. Command list. 

command. (1) A request from a terminal for the per- 
formance of an operation or the execution of a partic- 
ular program. (2) In SNA, any field set in the 
transmission header (TH), request header (RH), and 
sometimes portions of a request unit (RU), that initiates 
an action or that begins a protocol; for example: (a) 
Bind Session (session-control request unit), a 
command that activates an LU-LU session, (b) the 
change-direction indicator in the RH of the last RU of a 
chain, (c) the virtual route reset window indicator in a 
FID4 transmission header. See also VTAM operator 
command. 

command facility. The component of the NetView 
program that is a base for command processors that 
can monitor, control, automate, and improve the opera- 
tion of a network. 

command list. A list of commands and statements 
designed to perform a specific function for the user. 
Command lists can be written in REXX or in NetView 
command list language. 

command processor. (1) A program that performs an 
operation specified by a command. (2) In the NetView 
program, a user-written module designed to perform a 
specific function. Command processors, which can be 
written in assembler or a high-level language (HLL), 
are invoked as commands. 



the operator to enter NetView commands, and (c) can 
resume when such commands are complete. 

composite end node (CEN). A group of nodes made up 
of a single type 5 node and its subordinate type 4 nodes 
that together support type 2.1 protocols. To a type 2.1 
node, a CEN appears as one end node. For example, 
NCP and VTAM act as a composite end node. 

configuration. (1) (TC97) The arrangement of a com- 
puter system or network as defined by the nature, 
number, and the chief characteristics of its functional 
units. The term may refer to a hardware or a software 
configuration. (2) The devices and programs that 
make up a system, subsystem, or network. (3) In CCP, 
the arrangement of controllers, lines, and terminals 
attached to an IBM 3710 Network Controller. Also, the 
collective set of item definitions that describe such a 
configuration. 

configuration services. In SNA, one of the types of 
network services in the control point (CP) and in the 
physical unit (PU); configuration services activate, 
deactivate, and maintain the status of physical units, 
links, and link stations. Configuration services also 
shut down and restart network elements and modify 
path control routing tables and address-translation 
tables. See also maintenance services, management 
services, network services, and session services. 

connection. Synonym for physical connection. 

control program (CP). The VM operating system that 
manages the real processor's resources and is respon- 
sible for simulating System/370s for individual users. 

controlling application program. In VTAM, an applica- 
tion program with which a secondary logical unit (other 
than an application program) is automatically put in 
session whenever the secondary logical unit is avail- 
able. See also automatic logon and controlling logical 
unit. 



communication line. Deprecated term for telecommu- 
nication line and transmission line. 

communication management configuration host node. 

The type 5 host processor in a communication manage- 
ment configuration that does all network-control func- 
tions in the network except for the control of devices 
channel-attached to data hosts. Synonymous with com- 
munication management host. Contrast with data host 
node. 

communication management host. Synonym for com- 
munication management configuration host node. Con- 
trast with dafa host. 

component. A command that (a) controls the termi- 
nal's screen (using the DSIPSS macro 
(TYPE = ASYPANEL) or the VIEW command), (b) allows 



controlling logical unit, in VTAM, a logical unit with 
which a secondary logical unit (other than an applica- 
tion program) is automatically put in session whenever 
the secondary logical unit is available. A controlling 
logical unit can be either an application program or a 
device-type logical unit. See also automatic logon and 
controlling application program. 

control statement. A statement in a command list that 
controls the processing sequence of the command list 
or allows the command list to send messages to the 
operator and receive input from the operator. 

converted command. An intermediate form of a 
character-coded command produced by VTAM through 
use of an unformatted system services definition table. 
The format of a converted command is fixed; the unfor- 
matted system services definition table must be con- 
structed in such a manner that the character-coded 
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command (as entered by a logical unit) is converted 
into the predefined, converted command format. See 
also unformatted. 

cross-domain. In SNA, pertaining to control of 
resources involving more than one domain. 



definition statement. (1) In VTAM, the statement that 
describes an element of the network. (2) In NCP, a 
type of instruction that defines a resource to the NCP. 
See Figure 142, Figure 143, and Figure 144. See also 
macroinstruction. 



Customer Information Control System (CICS). A 

licensed program that enables transactions entered at 
remote terminals to be processed concurrently by 
user-written application programs. It also includes 
facilities for building, using, and maintaining data 
bases. 

data host. Synonym for data host node. Contrast with 
communication management configuration host. 

data host node. In a communication management con- 
figuration, a type 5 host node that is dedicated to proc- 
essing applications and does not control network 
resources, except for its channel-attached or communi- 
cation adapter-attached devices. Synonymous with 
data host. Contrast with communication management 
configuration host node. 

data link. In SNA, synonym for link. 

data link control (DLC) layer. In SNA, the layer that 
consists of the link stations that schedule data transfer 
over a transmission medium connecting two nodes and 
perform error control for the link connection. Examples 
of data link control are SDLC for serial-by-bit link con- 
nection and data link control for the System/370 
channel. 

data set. The major unit of data storage and retrieval, 
consisting of a collection of data in one of several pre- 
scribed arrangements and described by control infor- 
mation to which the system has access. 

DBCS. Double-byte character set. 

ddname. Data definition name. 

deactivate. To take a resource of a node out of 
service, rendering it inoperable, or to place it in a state 
in which it cannot perform the functions for which it was 
designed. Contrast with activate. 

deallocate. A logical unit (LU) 6.2 application program 
interface (API) verb that terminates a conversation, 
thereby freeing the session for a future conversation. 
Contrast with allocate. 

definite response (DR). In SNA, a value in the 
form-of-response-requested field of the request header. 
The value directs the receiver of the request to return a 
response unconditionally, whether positive or negative, 
to that request. Contrast with exception response and 
no response. 



operands 



suboperands 



suboperands 



START A,(B,C), KEYW0RD1=D, KEYW0RD2=(E,F) 

I l i i I i 



statement positional 
identifier operands 



keyword 
operands 



statement 



Figure 142. Example of a Language Statement 



definition statement 

I 



suboperands 



BUILD CA=(caO[,cal][,ca2][,ca3]) 

I I I I 



definition 

statement 

identifier 



keyword 
operand 



Figure 143. NCP Examples 



definition 

statement 

identifier 



keyword operand 



PU 



suboperands 

I ' 1 

discnt=([yes|no][,f|nf] ) 



I 
definition statement 



VARY NET.ACT, ID=name, RNAME= (namel namel3) 

l I l I I I 



operator positional 
command operands 
operator ' 



suboperands 



operands 



operator command 
Figure 144. VTAM Examples 

device. An input/output unit such as a terminal, 
display, or printer. See attaching device. 

dial-out. Refers to the direction in which a switched 
connection is requested by a host or an NCP. 

directory. In VM, a control program (CP) disk that 
defines each virtual machine's normal configuration. 

disabled. In VTAM, pertaining to a logical unit (LU) 
that has indicated to its system services control point 
(SSCP) that it is temporarily not ready to establish 
LU-LU sessions. An initiate request for a session with 
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a disabled logical unit (LU) can specify that the session 
be queued by the SSCP until the LU becomes enabled. 
The LU can separately indicate whether this applies to 
its ability to act as a primary logical unit (PLU) or a sec- 
ondary logical unit (SLU). See also enabled and inhib- 
ited. 

display. (1) To present information for viewing, 
usually on a terminal screen or a hard-copy device. 
(2) A device or medium on which information is pre- 
sented, such as a terminal screen. (3) Deprecated 
term for panel. 

domain. (1) An access method, its application pro- 
grams, communication controllers, connecting lines, 
modems, and attached terminals. (2) In SNA, a system 
services control point (SSCP) and the physical units 
(PUs), logical units (LUs), links, link stations, and all the 
associated resources that the SSCP has the ability to 
control by means of activation requests and deacti- 
vation requests. See system services control point 
domain and type 2.1 node control point domain.. See 
also single-domain network and multiple-domain 
network. 

domain operator. In a multiple-domain network, the 
person or program that controls the operation of the 
resources controlled by one system services control 
point. Contrast with network operator (2). 

double-byte character set (DBCS). A character set, 
such as Japanese, in which each character is repres- 
ented by a two-byte code. 

downstream. In the direction of data flow from the host 
to the end user. Contrast with upstream. 

DR. (1) In NCP and CCP, dynamic reconfiguration. 
(2) In SNA, definite response. 

drop. In the IBM Token-Ring Network, a cable that 
leads from a faceplate to the to the distribution panel in 
a wiring closet. When the IBM Cabling System is used 
with the IBM Token-Ring Network, a drop may form part 
of a lobe. 

dynamic reconfiguration (DR). The process of 
changing the network configuration (peripheral PUs 
and LUs) without regenerating complete configuration 
tables. 

EBCDIC. * Extended binary-coded decimal inter- 
change code. A coded character set consisting of 8-bit 
coded characters. 

echo. The return of characters to the originating SS 
device to verify that a message was sent correctly. 

element. (1) A field in the network address. (2) The 
particular resource within a subarea identified by the 
element address. See also subarea. 



Emulation Program (EP). An IBM control program that 
allows a channel-attached 3705 or 3725 communication 
controller to emulate the functions of an IBM 2701 Data 
Adapter Unit, an IBM 2702 Transmission Control, or an 
IBM 2703 Transmission Control. See also network 
control program. 

enabled. In VTAM, pertaining to a logical unit (LU) that 
has indicated to its system services control point 
(SSCP) that it is now ready to establish LU-LU sessions. 
The LU can separately indicate whether this prevents it 
from acting as a primary logical unit (PLU) or as a sec- 
ondary logical unit (SLU). See also disabled and inhib- 
ited. 

end node. A type 2.1 node that does not provide any 
intermediate routing or session services to any other 
node. For example, APPC/PC is an end node. See 
composite end node, node, and fype 2.1 node. 

EP. Emulation Program. 

ER. (1) Explicit route. (2) Exception response. 

error-to-traffic (E/T). The number of temporary errors 
compared to the traffic associated with a resource. 

E/T. Error-to-traffic. 

event. (1) In the NetView program, a record indicating 
irregularities of operation in physical elements of a 
network. (2) An occurrence of significance to a task; 
typically, the completion of an asynchronous operation, 
such as an input/output operation. 

exception response (ER). In SNA, a value in the 
form-of-response-requested field of a request header 
(RH). An exception response is sent only if a request is 
unacceptable as received or cannot be processed. 
Contrast with definite response and no response. See 
also negative response. 

EXEC. In a VM operating system, a user-written 
command file that contains CMS commands, other 
user-written commands, and execution control state- 
ments, such as branches. 

exit routine. Any of several types of special-purpose 
user-written routines. See accounting exit routine, 
authorization exit routine, logon-interpret routine, 
virtual route selection exit routine, EXLST exit routine, 
and RPL exit routine. 

EXLST exit routine. In VTAM, a routine whose address 
has been placed in an exit list (EXLST) control block. 
The addresses are placed there with the EXLST macro- 
instruction, and the routines are named according to 
their corresponding operand; hence DFASY exit 
routine, TPEND exit routine, RELREQ exit routine, and 
so forth. All exit list routines are coded by the VTAM 
application programmer. Contrast with RPL exit 
routine. 
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explicit route (ER). In SNA, the path control network 
elements, including a specific set of one or more trans- 
mission groups, that connect two subarea nodes. An 
explicit route is identified by an origin subarea 
address, a destination subarea address, an explicit 
route number, and a reverse explicit route number. 
Contrast with virtual route (VR). See also path and 
route extension. 

feature. A particular part of an IBM product that a cus- 
tomer can order separately. 

FID. Format identification. 

field-formatted. Pertaining to a request or response 
that is encoded into fields, each having a specified 
format such as binary codes, bit-significant flags, and 
symbolic names. Contrast with character-coded. 

flow control. In SNA, the process of managing the rate 
at which data traffic passes between components of the 
network. The purpose of flow control is to optimize the 
rate of flow of message units, with minimum congestion 
in the network; that is, to neither overflow the buffers at 
the receiver or at intermediate routing nodes, nor leave 
the receiver waiting for more message units. See also 
adaptive session-level pacing, pacing, session-level 
pacing, and virtual route pacing. 

flushing. In logical unit (LU) 6.2, the process of 
sending through the network all remaining buffered 
data generated by a transaction program. The trans- 
action program issues the flush verb to begin the 
process. It also occurs if the network operator issues 
the command. 

format identification (FID) field. In SNA, a field in each 
transmission header (TH) that indicates the format of 
the TH; that is, the presence or absence of certain 
fields. TH formats differ in accordance with the types of 
nodes between which they pass. The six FID types are: 

FIDO, used for traffic involving non-SNA devices 
between adjacent subarea nodes when either or 
both nodes do not support explicit route and virtual 
route protocols. 

FID1, used for traffic between adjacent subarea 
nodes when either or both nodes do not support 
explicit route and virtual route protocols. 

FID2, used for traffic between a subarea node and 
an adjacent type 2 peripheral node. 

FID3, used for traffic between a subarea node and 
an adjacent type 1 peripheral node. 

FID4, used for traffic between adjacent subarea 
nodes when both nodes support explicit route and 
virtual route protocols. 

FIDF, used for certain commands (for example, for 
transmission group control) sent between adjacent 
subarea nodes when both nodes support explicit 
route and virtual route protocols. 



frame. (1) The unit of transmission in some local area 
networks, including the IBM Token-Ring Network. It 
includes delimiters, control characters, information, 
and checking characters. (2) In SDLC, the vehicle for 
every command, every response, and all information 
that is transmitted using SDLC procedures. 

full-screen mode. A form of panel presentation in the 
NetView program where the contents of an entire ter- 
minal screen can be displayed at once. Full-screen 
mode can be used for fill-in-the-blanks prompting. Con- 
trast with line mode. 

GCS. Group control system. 

generation. The process of assembling and link 
editing definition statements so that resources can be 
identified to all the necessary programs in a network. 

generic alert. Encoded alert information that uses 
code points (defined by IBM and possibly customized 
by users or application programs) stored at an alert 
receiver, such as the NetView program. 

group. In the NetView/PC program, to identify a set of 
application programs that are to run concurrently. 

group control system (GCS). A component of VM that 
provides multiprogramming and shared memory 
support to virtual machines. It is a saved system 
intended for use with SNA products. 

half-session. In SNA, a component that provides func- 
tion management data (FMD) services, data flow 
control, and transmission control for one of the ses- 
sions of a network addressable unit (NAU). See also 
primary half-session and secondary half-session. 

hard copy. A printed copy of machine output in a visu- 
ally readable form; for example, printed reports, 
listings, documents, summaries, or network logs. 

hardware monitor. The component of the NetView 
program that helps identify network problems, such as 
hardware, software, and microcode, from a central 
control point using interactive display techniques. 

HCF. Host Command Facility. 

help panel. An online display that tells you how to use 
a command or another aspect of a product. See task 
panel. 

High Performance Option (HPO). A licensed program 
that is an extension of VM/SP. It provides performance 
and operation enhancements for large system environ- 
ments. 

Host Command Facility (HCF). An IBM licensed 
program that enables a user at a System/370 terminal 
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to access applications in systems such as the 8100 or 
System/36. 

host node. A node providing an application program 
interface (API) and a common application interface. 
See boundary node, node, peripheral node, subarea 
host node, and subarea node. See also boundary func- 
tion and node type. 

HPO. High Performance Option. 

IMS. Information Management System/Virtual Storage. 
Synonymous with IMS/VS. 

IMS/VS. Information Management System/Virtual 
Storage. Synonym for IMS. 

Inactive. Describes the state of a resource that has not 
been activated or for which the VARY INACT command 
has been issued. Contrast with active. See also inop- 
erative. 



information (I) format. 

transfer. 



A format used for information 



information/Management. A feature of the 
Information/System licensed program that provides 
interactive systems management applications for 
problem, change, and configuration management. 

Information Management System (IMS). A general 
purpose system whose full name is Information Man- 
agement System/Virtual Storage (IMS/VS). It enhances 
the capabilities of OS/VS for batch processing and tele- 
communication and allows users to access a 
computer-maintained data base through remote termi- 
nals. 

inhibited. In VTAM, pertaining to a logical unit (LU) 
that has indicated to its system services control point 
(SSCP) that it is not ready to establish LU-LU sessions. 
An initiate request for a session with an inhibited LU 
will be rejected by the SSCP. The LU can separately 
indicate whether this applies to its ability to act as a 
primary logical unit (PLU) or as a secondary logical 
unit (SLU). See also enabled and disabled. 



programs, it provides a means of generating standard 
screen panels and interactive dialogues between the 
application programmer and terminal user. 

interface. * A shared boundary. An interface might be 
a hardware component to link two devices or it might 
be a portion of storage or registers accessed by two or 
more computer programs. 

ISPF. Interactive System Productivity Facility. 

item. In CCP, any of the components, such as commu- 
nication controllers, lines, cluster controllers, and ter- 
minals, that comprise an IBM 3710 Network Controller 
configuration. 

JCL. Job control language. 

Job control language (JCL). * A problem-oriented lan- 
guage designed to express statements in a job that are 
used to identify the job or describe its requirements to 
an operating system. 

Kanji. An ideographic character set used in Japanese. 
See also double-byte character set. 

keyword. (1) (TC97) A lexical unit that, in certain con- 
texts, characterizes some language construction. (2) * 
One of the predefined words of an artificial language. 
(3) One of the significant and informative words in a 
title or document that describes the content of that doc- 
ument. (4) A name or symbol that identifies a param- 
eter. (5) A part of a command operand that consists of 
a specific character string (such as DSNAME = ). See 
also definition statement and keyword operand. Con- 
trast with positional operand. 

keyword operand. An operand that consists of a 
keyword followed by one or more values (such as 
DSNAME = HELLO). See also definition statement. 
Contrast with positional operand. 

keyword parameter. A parameter that consists of a 
keyword followed by one or more values. 

line. See communication line. 



initiate. A network services request sent from a logical 
unit (LU) to a system services control point (SSCP) 
requesting that an LU-LU session be established. 

inoperative. The condition of a resource that has been 
active, but is not. The resource may have failed, 
received an INOP request, or is suspended while a 
reactivate command is being processed. See also 
inactive. 

interactive System Productivity Facility (ISPF). An IBM 

licensed program that serves as a full-screen editor 
and dialogue manager. Used for writing application 



line mode. A form of screen presentation in which the 
information is presented a line at a time in the message 
area of the terminal screen. Contrast with full-screen 
mode. 

link. In SNA, the combination of the link connection 
and the link stations joining network nodes; for 
example: (1) a System/370 channel and its associated 
protocols, (2) a serial-by-bit connection under the 
control of Synchronous Data Link Control (SDLC). A 
link connection is the physical medium of transmission. 
A link, however, is both logical and physical. Synony- 
mous with data link. See Figure 145 on page 230. 
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Figure 145. Links and Path Controls 

link-attached. Pertaining to devices that are physically 
connected by a telecommunication line. Contrast with 
channel-attached. Synonymous with remote. 

link connection segment. A portion of the configuration 
that is located between two resources listed consec- 
utively in the service point command service (SPCS) 
query link configuration request list. 



load module. (ISO) A program unit that is suitable for 
loading into main storage for execution; it is usually the 
output of a linkage editor. 

local. Pertaining to a device that is attached to a con- 
trolling unit by cables, rather than by a telecommuni- 
cation line. Synonymous with channel-attached. 
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local address. In SNA, an address used in a peripheral 
node in place of an SNA network address and trans- 
formed to or from an SNA network address by the 
boundary function in a subarea node. 

logical unit (LU). In SNA, a port through which an end 
user accesses the SNA network and the functions pro- 
vided by system services control points (SSCPs). An 
LU can support at least two sessions— one with an 
SSCP and one with another LU— and may be capable of 
supporting many sessions with other LUs. See also 
network addressable unit (NAU), peripheral LU, phys- 
ical unit (PU), system services control point (SSCP), 
primary logical unit (PLU), and secondary logical unit 
(SLU). 

logical unit (LU) services. In SNA, capabilities in a 
logical unit to: (1) receive requests from an end user 
and, in turn, issue requests to the system services 
control point (SSCP) in order to perform the requested 
functions, typically for session initiation; (2) receive 
requests from the SSCP, for example to activate LU-LU 
sessions via Bind Session requests; and (3) provide 
session presentation and other services for LU-LU ses- 
sions. See also physical unit (PU) services. 

logical unit (LU) 6.2. A type of logical unit that sup- 
ports general communication between programs in a 
distributed processing environment. LU 6.2 is charac- 
terized by (1) a peer relationship between session part- 
ners, (2) efficient utilization of a session for multiple 
transactions, (3) comprehensive end-to-end error proc- 
essing, and (4) a generic application program interface 
(API) consisting of structured verbs that are mapped 
into a product implementation. 

logoff. In VTAM, an unformatted session termination 
request. 

logon. In VTAM, an unformatted session initiation 
request for a session between two logical units. See 
automatic logon and simulated logon. See also 
session-initiation request. 

logon-interpret routine. In VTAM, an installation exit 
routine, associated with an interpret table entry, that 
translates logon information. It may also verify the 
logon. 

LU. Logical unit. 

LU type. In SNA, the classification of an LU-LU session 
in terms of the specific subset of SNA protocols and 
options supported by the logical units (LUs) for that 
session, namely: 

The mandatory and optional values allowed in the 
session activation request. 

The usage of data stream controls, function man- 
agement headers (FMHs), request unit (RU) param- 
eters, and sense codes. 



Presentation services protocols such as those 
associated with FMH usage. 

LU types 0, 1, 2, 3, 4, 6.1, 6.2, and 7 are defined. 

LU-LU session. In SNA, a session between two logical 
units (LUs) in an SNA network. It provides communi- 
cation between two end users, or between an end user 
and an LU services component. 

LU-LU session type. A deprecated term for LU type. 

LU6.2. Logical unit 6.2. 

macroinstruction. (1) An instruction that when exe- 
cuted causes the execution of a predefined sequence of 
instructions in the same source language. (2) In 
assembler programming, an assembler language state- 
ment that causes the assembler to process a prede- 
fined set of statements called a macro definition. The 
statements normally produced from the macro defi- 
nition replace the macroinstruction in the program. 
See also definition statement. 

maintenance services. In SNA, one of the types of 
network services in system services control points 
(SSCPs) and physical units (PUs). Maintenance ser- 
vices provide facilities for testing links and nodes and 
for collecting and recording error information. See 
also configuration services, management services, 
network services, and session services. 

major node. In VTAM, a set of resources that can be 
activated and deactivated as a group. See node and 
minor node. 

management services. In SNA, one of the types of 
network services in control points (CPs) and physical 
units (PUs). Management services are the services 
provided to assist in the management of SNA networks, 
such as problem management, performance and 
accounting management, configuration management 
and change management. See also configuration ser- 
vices, maintenance services, network services, and 
session services. 

message. (1) (TC97) A group of characters and 
control bit sequences transferred as an entity. (2) In 
VTAM, the amount of function management data (FMD) 
transferred to VTAM by the application program with 
one SEND request. 

migration, installing a new version or release of a 
program when an earlier version or release is already 
in place. 

minidisk. Synonym for virtual disk. 

minor node. In VTAM, a uniquely-defined resource 
within a major node. See node and major node. 
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module. * A program unit that is discrete and identifi- 
able with respect to compiling, combining with other 
units, and loading; for example, the input to or output 
from an assembler, compiler, linkage editor, or execu- 
tive routine. 

monitor. In the IBM Token-Ring Network, the function 
required to initiate the transmission of a token on the 
ring and to provide soft-error recovery in case of lost 
tokens, circulating frames, or other difficulties. The 
capability is present in all ring stations. 

multiple-domain network. In SNA, a network with more 
than one system services control point (SSCP). Con- 
trast with single-domain network. 

Multiple Virtual Storage (MVS). An IBM licensed 
program whose full name is the Operating 
System/Virtual Storage (OS/VS) with Multiple Virtual 
Storage/System Product for System/370. It is a soft- 
ware operating system controlling the execution of pro- 
grams. 

Multiple Virtual Storage for Extended Architecture 
(MVS/XA). An IBM licensed program whose full name 
is the Operating System/Virtual Storage (OS/VS) with 
Multiple Virtual Storage/System Product for Extended 
Architecture. Extended architecture allows 31-bit 
storage addressing. MVS/XA is a software operating 
system controlling the execution of programs. 

MVS. Multiple Virtual Storage operating system. 

MVS/OCCF. Multiple Virtual Storage/Operator Com- 
munication Control Facility. 

MVS/XA. Multiple Virtual Storage for Extended Archi- 
tecture operating system. 

NAU. Network addressable unit. 

NCCF. Network Communications Control Facility. 

NCP. (1) Network Control Program (IBM licensed 
program). Its full name is Advanced Communications 
Function for the Network Control Program. Synony- 
mous with ACF/NCP. (2) Network control program 
(general term). 

negative response (NR). In SNA, a response indicating 
that a request did not arrive successfully or was not 
processed successfully by the receiver. Contrast with 
positive response. See exception response. 

NetView. A system 370-based IBM licensed program 
used to monitor a network, manage it, and diagnose its 
problems. 

NetView command list language. An interpretive lan- 
guage unique to the NetView program that is used to 
write command lists. 



NetView-NetView task (NNT). The task under which a 
cross-domain NetView operator session runs. See 
operator station task. 

NetView/PC. A PC-based IBM licensed program 
through which application programs can be used to 
monitor, manage, and diagnose problems in IBM 
Token-Ring networks, non-SNA communication 
devices, and voice networks. 

network. (1) (TC97) An interconnected group of 
nodes. (2) In data processing, a user application 
network. See path control network, public network, 
SNA network, subarea network, type 2.1 network, and 
user-application network. 

network address. In SNA, an address, consisting of 
subarea and element fields, that identifies a link, a link 
station, or a network addressable unit. Subarea nodes 
use network addresses; peripheral nodes use local 
addresses. The boundary function in the subarea node 
to which a peripheral node is attached transforms local 
addresses to network addresses and vice versa. See 
local address. See also network name. 

network addressable unit (NAU). In SNA, a logical unit, 
a physical unit, or a system services control point. It is 
the origin or the destination of information transmitted 
by the path control network. Each NAU has a network 
address that represents it to the path control network. 
See also network name, network address, and path 
control network. 

Network Communications Control Facility (NCCF). An 

IBM licensed program that is a base for command 
processors that can monitor, control, automate, and 
improve the operations of a network. Its function is 
included and enhanced in NetView's command facility. 

network control (NC). In SNA, an RU category used for 
requests and responses exchanged for such purposes 
as activating and deactivating explicit and virtual 
routes and sending load modules to adjacent periph- 
eral nodes. See also data flow control layer and 
session control. 

Network Control Program (NCP). An IBM licensed 
program that provides communication controller 
support for single-domain, multiple-domain, and inter- 
connected network capability. Its full name is 
Advanced Communications Function for the Network 
Control Program. 

network control program. A program, generated by 
the user from a library of IBM-supplied modules, that 
controls the operation of a communication controller. 

network identifier (network ID). The network name 
defined to NCPs and hosts to indicate the name of the 
network in which they reside. It is unique across all 
communicating SNA networks, communication among 
domains. 
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Network Logical Data Manager (NLDM). An IBM 

licensed program that collects and correlates 
session-related data and provides online access to this 
information. It runs as an NCCF communication 
network management (CNM) application program. Its 
function is included and enhanced in NetView's session 
monitor. 

network name. (1) In SNA, the symbolic identifier by 
which end users refer to a network addressable unit 
(NAU), a link, or a link station. See also network 
address. (2) In a multiple-domain network, the name 
of the APPL statement defining a VTAM application 
program is its network name and it must be unique 
across domains. Contrast with ACB name. See unin- 
terpreted name. 

network operator. (1) . A person or program respon- 
sible for controlling the operation of all or part of a 
network. (2) The person or program that controls all 
the domains in a multiple-domain network. Contrast 
with domain operator. 

Network Problem Determination Application (NPDA). 

An IBM licensed program that helps you identify 
network problems, such as hardware, software, and 
microcode, from a central control point using interac- 
tive display techniques. It runs as an NCCF communi- 
cation network management (CNM) application 
program. Its function is included and enhanced in 
NetView's hardware monitor. 

network services (NS). In SNA, the services within 
network addressable units (NAUs) that control network 
operation through SSCP-SSCP, SSCP-PU, and SSCP-LU 
sessions. See configuration services, maintenance 
services, management services, and session services. 

NLDM. Network Logical Data Manager. 

NNT. NetView-NetView task. 

node. (1) In SNA, an endpoint of a link or junction 
common to two or more links in a network. Nodes can 
be distributed to host processors, communication con- 
trollers, cluster controllers, or terminals. Nodes can 
vary in routing and other functional capabilities. See 
boundary node, host node, peripheral node, and 
subarea node (including illustration). (2) In VTAM, a 
point in a network defined by a symbolic name. See 
major node and minor node. 

node name. In VTAM, the symbolic name assigned to 
a specific major or minor node during network defi- 
nition. 

node type. In SNA, a designation of a node according 
to the protocols it supports and the network address- 
able units (NAUs) that it can contain. Five types are 
defined: 1, 2.0, 2.1, 4, and 5. Type 1, type 2.0, and type 
2.1 nodes are peripheral nodes; type 4 and type 5 
nodes are subarea nodes. See also type 2.1 node. 



no response. In SNA, a value in the 
form-of-response-requested field of the request header 
(RH) indicating that no response is to be returned to the 
request, whether or not the request is received and 
processed successfully. Contrast with definite 
response and exception response. 

notify. A network services request that is sent by an 
SSCP to a logical unit (LU) to inform the LU of the status 
of a procedure requested by the LU. 

NPDA. Network Problem Determination Application. 

OCCF. Operator Communication Control Facility. 

online. Stored in a computer and accessible from a 
terminal. 

operand. (1) (ISO) An entity on which an operation is 
performed. (2) * That which is operated upon. An 
operand is usually identified by an address part of an 
instruction. (3) Information entered with a command 
name to define the data on which a command 
processor operates and to control the execution of the 
command processor. (4) An expression to whose 
value an operator is applied. See also definition state- 
ment, keyword, keyword parameter, and parameter. 

operator. (1) In a language statement, the lexical 
entity that indicates the action to be performed on oper- 
ands. (2) A person who operates a machine. See 
network operator. See also definition statement. 

Operator Communication Control Facility (OCCF). A 

licensed program that allows communication with and 
the operation of remote MVS or VSE systems. 

operator profile. In the NetView program, the 
resources and activities a network operator has control 
over. The statements defining these resources and 
activities are stored in a file that is activated when the 
operator logs on. 

operator station task (OST). The NetView task that 
establishes and maintains the online session with the 
network operator. There is one operator station task 
for each network operator who logs on to the NetView 
program. See NetView-NetView task. 

OST. Operator station task. 

pacing. In SNA, a technique by which a receiving com- 
ponent controls the rate of transmission of a sending 
component to prevent overrun or congestion. See 
session-level pacing, send pacing, and virtual route 
(VR) pacing. See also flow control. 

page. (1) The portion of a panel that is shown on a 
display surface at one time. (2) To move back and 
forth among the pages of a multiple-page panel. See 
also scroll. (3) (ISO) In a virtual storage system, a 
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fixed-length block that has a virtual address and that 
can be transferred between real storage and auxiliary 
storage. (4) To transfer instructions, data, or both 
between real storage and external page or auxiliary 
storage. 

panel. (1) A formatted display of information that 
appears on a terminal screen. See also help panel and 
task panel. Contrast with screen. (2) In computer 
graphics, a display image that defines the locations and 
characteristics of display fields on a display surface. 

parameter. (1) (ISO) A variable that is given a con- 
stant value for a specified application and that may 
denote the application. (2) An item in a menu for 
which the user specifies a value or for which the 
system provides a value when the menu is interpreted. 
(3) Data passed to a program or procedure by a user 
or another program, namely as an operand in a lan- 
guage statement, as an item in a menu, or as a shared 
data structure. See also keyword, keyword parameter, 
and operand. 

path. (1) In SNA, the series of path control network 
components (path control and data link control) that are 
traversed by the information exchanged between two 
network addressable units (NAUs). See also explicit 
route (ER), route extension, and virtual route (VR). 
(2) In VTAM when defining a switched major node, a 
potential dial-out port that can be used to reach that 
node. (3) In the NetView/PC program, a complete line 
in a configuration that contains all of the resources in 
the service point command service (SPCS) query link 
configuration request list. 

path control (PC). The function that routes message 
units between network addressable units (NAUs) in the 
network and provides the paths between them. It con- 
verts the BlUs from transmission control (possibly seg- 
menting them) into path information units (PIUs) and 
exchanges basic transmission units (BTUs) and one or 
more PIUs with data link control. Path control differs 
for peripheral nodes, which use local addresses for 
routing, and subarea nodes, which use network 
addresses for routing. See peripheral path control and 
subarea path control. See also link, peripheral node, 
and subarea node. 

path control (PC) layer. In SNA, the layer that 
manages the sharing of link resources of the SNA 
network and routes basic information units (BlUs) 
through it. See also BIU segment, blocking of PIUs, 
data link control layer, and transmission control layer. 

path control (PC) network. In SNA, the part of the SNA 
network that includes the data link control and path 
control layers. See SNA network and user application 
network. See also boundary function. 

PC. (1) Path control. (2) Personal Computer. Its full 
name is the IBM Personal Computer. 



peripheral host node. A node that provides an applica- 
tion program interface (API) for running application 
programs but does not provide SSCP functions and is 
not aware of the network configuration. The peripheral 
host node does not provide subarea node services. It 
has boundary function provided by its adjacent 
subarea. See boundary node, host node, node, periph- 
eral node, subarea host node, and subarea node. See 
also boundary function and node type. 

peripheral LU. In SNA, a logical unit representing a 
peripheral node. 

peripheral node. In SNA, a node that uses local 
addresses for routing and therefore is not affected by 
changes in network addresses. A peripheral node 
requires boundary-function assistance from an adja- 
cent subarea node. A peripheral node is a physical 
unit (PU) type 1, 2.0, or 2.1 node connected to a 
subarea node with boundary function within a subarea. 
See boundary node, host node, node, peripheral host 
node, subarea host node, and subarea node. See also 
boundary function and node type. 

peripheral path control. The function in a peripheral 
node that routes message units between units with 
local addresses and provides the paths between them. 
See path control and subarea path control. See also 
boundary function, peripheral node, and subarea node. 

peripheral PU. In SNA, a physical unit representing a 
peripheral node. 

Personal Computer (PC). The IBM Personal Computer 
line of products including the 5150 and subsequent 
models. 

physical connection. In VTAM, a point-to-point con- 
nection or multipoint connection. Synonymous with 
connection. 

physical unit (PU). In SNA, a type of network address- 
able unit (NAU). A physical unit (PU) manages and 
monitors the resources (such as attached links) of a 
node, as requested by a system services control point 
(SSCP) through an SSCP-PU session. An SSCP acti- 
vates a session with the physical unit in order to indi- 
rectly manage, through the PU, resources of the node 
such as attached links. See also peripheral PU and 
subarea PU. 

physical unit (PU) services. In SNA, the components 
within a physical unit (PU) that provide configuration 
services and maintenance services for SSCP-PU ses- 
sions. See also logical unit (LU) services. 

PLU. Primary logical unit. 

POI. Programmed operator interface. 
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positional operand. An operand in a language state- 
ment that has a fixed position. See also definition 
statement. Contrast with keyword operand. 

positive response. A response indicating that a 
request was received and processed. Contrast with 
negative response. 

PPT. Primary POI task. 

primary half-session. In SNA, the half-session that 
sends the session activation request. See also primary 
logical unit. Contrast with secondary half-session. 



receive pacing. In SNA, the pacing of message units 
that the component is receiving. See also send pacing. 

record. (1) (ISO) In programming languages, an 
aggregate that consists of data objects, possibly with 
different attributes, that usually have identifiers 
attached to them. In some programming languages, 
records are called structures. (2) (TC97) A set of data 
treated as a unit. (3) A set of one or more related data 
items grouped for processing. (4) In VTAM, the unit of 
data transmission for record mode. A record repres- 
ents whatever amount of data the transmitting node 
chooses to send. 



primary logical unit (PLU). In SNA, the logical unit (LU) 
that contains the primary half-session for a particular 
LU-LU session. Each session must have a PLU and 
secondary logical unit (SLU). The PLU is the unit 
responsible for the bind and is the controlling LU for 
the session. A particular LU may contain both primary 
and secondary half-sessions for different active LU-LU 
sessions. Contrast with secondary logical unit (SLU). 

primary POI task (PPT). The NetView subtask that 
processes all unsolicited messages received from the 
VTAM program operator interface (POI) and delivers 
them to the controlling operator or to the command 
processor. The PPT also processes the initial 
command specified to execute when the NetView 
program is initialized and timer request commands 
scheduled to execute under the PPT. 

problem determination. The process of identifying the 
source of a problem; for example, a program compo- 
nent, a machine failure, telecommunication facilities, 
user or contractor-installed programs or equipment, an 
environment failure such as a power loss, or a user 
error. 

profile. In the Conversational Monitor System (CMS) 
or the group control system (GCS), the characteristics 
defined by a PROFILE EXEC file that executes automat- 
ically after the system is loaded into a virtual machine. 
See also operator profile. 

programmed operator interface (POI). A VTAM func- 
tion that allows programs to perform VTAM operator 
functions. 

PU. Physical unit. 

public network. A network established and operated 
by communication common carriers or telecommuni- 
cation Administrations for the specific purpose of pro- 
viding circuit-switched, packet switched, and 
leased-circuit services to the public. Contrast with 
user-application network. 

PU-PU flow. In SNA, the exchange between physical 
units (PUs) of network control requests and responses. 



release. For VTAM, to relinquish control of resources 
(communication controllers or physical units). See also 
resource takeover. Contrast with acquire (2). 

remote. Concerning the peripheral parts of a network 
not centrally linked to the host processor and generally 
using telecommunication lines with public right-of-way. 

remove. In the IBM Token-Ring Network, to take an 
attaching device off the ring. 

reset. On a virtual circuit, reinitialization of data flow 
control. At reset, all data in transit are eliminated. 

resource. (1) Any facility of the computing system or 
operating system required by a job or task, and 
including main storage, input/output devices, the proc- 
essing unit, data sets, and control or processing pro- 
grams. (2) In the NetView program, any hardware or 
software that provides function to the network. 

resource takeover. In VTAM, action initiated by a 
network operator to transfer control of resources from 
one domain to another. See also acquire (2) and 
release. See takeover. 

response. A reply represented in the control field of a 
response frame. It advises the primary or combined 
station of the action taken by the secondary or other 
combined station to one or more commands. See also 
command. 

Restructured Extended Executor (REXX). An interpre- 
tive language used to write command lists. 

return code. * A code [returned from a program] used 
to influence the execution of succeeding instructions. 

REXX. Restructured Extended Executor. 

route. See explicit route and virtual route. 

route extension (REX). In SNA, the path control 
network components, including a peripheral link, that 
make up the portion of a path between a subarea node 
and a network addressable unit (NAU) in an adjacent 
peripheral node. See also path, explicit route (ER) and 
virtual route (VR). 
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routing. The assignment of the path by which a 
message will reach its destination. 

RPL exit routine. In VTAM, an application program exit 
routine whose address has been placed in the EXIT 
field of a request parameter list (RPL). VTAM invokes 
the routine to indicate that an asynchronous request 
has been completed. See EXLST exit routine. 

RU chain. In SNA, a set of related request/response 
units (RUs) that are consecutively transmitted on a par- 
ticular normal or expedited data flow. The request RU 
chain is the unit of recovery: if one of the RUs in the 
chain cannot be processed, the entire chain is dis- 
carded. Each RU belongs to only one chain, which has 
a beginning and an end indicated by means of control 
bits in request/response headers within the RU chain. 
Each RU can be designated as first-in-chain (FIC), 
iast-in-chain (LIC), middle-in-chain (MIC), or 
only-in-chain (OIC). Response units and expedited-flow 
request units are always sent as only-in-chain. 

scope of commands. In the NetView program, the 
facility that provides the ability to assign different 
responsibilities to various operators. 

screen. An illuminated display surface; for example, 
the display surface of a CRT or plasma panel. Contrast 
with panel. 

scroll. To move all or part of the display image verti- 
cally to display data that cannot be observed within a 
single display image. See also page (2). 

secondary half-session. In SNA, the half-session that 
receives the session-activation request. See also sec- 
ondary logical unit (SLU). Contrast with primary 
half-session. 

secondary logical unit (SLU). In SNA, the logical unit 
(LU) that contains the secondary half-session for a par- 
ticular LU-LU session. An LU may contain secondary 
and primary half-sessions for different active LU-LU 
sessions. Contrast with primary logical unit (PLU). 

secondary logical unit (SLU) key. A key-encrypting key 
used to protect a session cryptography key during its 
transmission to the secondary half-session. 

segment. (1) In the IBM Token-Ring Network, a 
section of cable between components or devices on the 
network. A segment may consist of a single patch 
cable, multiple patch cables connected together, or a 
combination of building cable and patch cables con- 
nected together. (2) See link connection segment. 

send pacing. In SNA, pacing of message units that a 
component is sending. See also receive pacing. 

sequence number. A number assigned to a particular 
frame or packet to control the transmission flow and 
receipt of data. 



service point (SP). An entry point that supports appli- 
cations that provide network management for 
resources not under the direct control of itself as an 
entry point. Each resource is either under the direct 
control of another entry point or not under the direct 
control of any entry point. A service point accessing 
these resources is not required to use SNA sessions 
(unlike a focal point). A service point is needed when 
entry point support is not yet available for some 
network management function. 

service point command service (SPCS). An extension 
of the command facility in the NetView program that 
allows the host processor to communicate with a 
service point by using the communication network 
management (CNM) interface. 

session. In SNA, a logical connection between two 
network addressable units (NAUs) that can be acti- 
vated, tailored to provide various protocols, and deacti- 
vated, as requested. Each session is uniquely 
identified in a transmission header (TH) by a pair of 
network addresses, identifying the origin and destina- 
tion NAUs of any transmissions exchanged during the 
session. See half-session, LU-LU session, SSCP-LU 
session, SSCP-PU session, and SSCP-SSCP session. 
See also LU-LU session type and PU-PU flow. 

session control (SC). In SNA, (1) One of the compo- 
nents of transmission control. Session control is used 
to purge data flowing in a session after an unrecover- 
able error occurs, to resynchronize the data flow after 
such an error, and to perform cryptographic verifica- 
tion. (2) A request unit (RU) category used for requests 
and responses exchanged between the session control 
components of a session and for session activation and 
deactivation requests and responses. 

session data. Data about a session, collected by the 
NetView program, that consists of session awareness 
data, session trace data, and session response time 
data. 

session-initiation request. In SNA, an Initiate or logon 
request from a logical unit (LU) to a control point (CP) 
that an LU-LU session be activated. 

session-level pacing. In SNA, a flow control technique 
that permits a receiver to control the data transfer rate 
(the rate at which it receives request units) on the 
normal flow. It is used to prevent overloading a 
receiver with unprocessed requests when the sender 
can generate requests faster than the receiver can 
process them. See also pacing and virtual route 
pacing. 

session monitor. The component of the NetView 
program that collects and correlates session-related 
data and provides online access to this information. 
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session services. In SNA, one of the types of network 
services in the control point (CP) and in the logical unit 
(LU). These services provide facilities for an LU or a 
network operator to request that the SSCP initiate or 
terminate sessions between logical units. See config- 
uration services, maintenance services, and manage- 
ment services. 

shared. Pertaining to the availability of a resource to 
more than one use at the same time. 

simulated logon. A session-initiation request gener- 
ated when a VTAM application program issues a 
SIMLOGON macroinstruction. The request specifies a 
logical unit (LU) with which the application program 
wants a session in which the requesting application 
program will act as the primary logical unit (PLU). 

single-domain network. In SNA, a network with one 
system services control point (SSCP). Contrast with 
multiple-domain network. 

SLU. Secondary logical unit. 

SMF. System management facility. 

SNA. Systems Network Architecture. 

SNA network. The part of a user-application network 
that conforms to the formats and protocols of Systems 
Network Architecture. It enables reliable transfer of 
data among end users and provides protocols for con- 
trolling the resources of various network configura- 
tions. The SNA network consists of network 
addressable units (NAUs), boundary function compo- 
nents, and the path control network. 

solicited message. A response from VTAM to a 
command entered by a program operator. Contrast 
with unsolicited message. 

SP. Service point. 

SPCS. Service point command service. 

span. In the NetView program, a user-defined group of 
network resources within a single domain. Each major 
or minor node is defined as belonging to one or more 
spans. See also span of control. 

span of control. The total network resources over 
which a particular network operator has control. All 
the network resources listed in spans associated 
through profile definition with a particular network 
operator are within that operator's span of control. 

SSCP. System services control point. 

SSCP-LU session. In SNA, a session between a 
system services control point (SSCP) and a logical unit 
(LU); the session enables the LU to request the SSCP to 
help initiate LU-LU sessions. 



SSCP-PU session. In SNA, a session between a 
system services control point (SSCP) and a physical 
unit (PU); SSCP-PU sessions allow SSCPs to send 
requests to and receive status information from indi- 
vidual nodes in order to control the network configura- 
tion. 

SSCP-SSCP session. In SNA, a session between the 
system services control point (SSCP) in one domain 
and the SSCP in another domain. An SSCP-SSCP 
session is used to initiate and terminate cross-domain 
LU-LU sessions. 

SSP. System Support Programs (IBM licensed 
program). Its full name is Advanced Communications 
Function for System Support Programs. Synonymous 
with ACF/SSP. 

statement. A language syntactic unit consisting of an 
operator, or other statement identifier, followed by one 
or more operands. See definition statement. 

station. (1) One of the input or output points of a 
network that uses communication facilities; for 
example, the telephone set in the telephone system or 
the point where the business machine interfaces with 
the channel on a leased private line. (2) One or more 
computers, terminals, or devices at a particular 
location. 

status monitor. A component of the NetView program 
that collects and summarizes information on the status 
of resources defined in a VTAM domain. 

subarea. A portion of the SNA network consisting of a 
subarea node, any attached peripheral nodes, and their 
associated resources. Within a subarea node, all 
network addressable units, links, and adjacent link 
stations (in attached peripheral or subarea nodes) that 
are addressable within the subarea share a common 
subarea address and have distinct element addresses. 

subarea host node. A host node that provides both 
subarea function and an application program interface 
(API) for running application programs. It provides 
system services control point (SSCP) functions, 
subarea node services, and is aware of the network 
configuration. See boundary node, communication 
management configuration host node, data host node, 
host node, node, peripheral node, and subarea node. 
See also boundary function and node type. 

subarea node. In SNA, a node that uses network 
addresses for routing and whose routing tables are 
therefore affected by changes in the configuration of 
the network. Subarea nodes can provide gateway func- 
tion, and boundary function support for peripheral 
nodes. Type 4 and type 5 nodes are subarea nodes. 
See boundary node, host node, node, peripheral node, 
and subarea host node. See also boundary function 
and node type. 
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subarea path control. The function in a subarea node 
that routes message units between network address- 
able units (NAUs) and provides the paths between 
them. See path control and peripheral path control. 
See also boundary function, peripheral node, and 
subarea node. 



subarea PU. 

node. 



In SNA, a physical unit (PU) in a subarea 



subsystem. A secondary or subordinate system, 
usually capable of operating independent of, or asyn- 
chronously with, a controlling system. 

supervisor call (SVC). A request that serves as the 
interface into operating system functions, such as allo- 
cating storage. The SVC protects the operating system 
from inappropriate user entry. All operating system 
requests must be handled by SVCs. 

supervisor call (SVC) instruction. An instruction that 
interrupts the program being executed and passes 
control to the supervisor so that it can perform a spe- 
cific service indicated by the instruction. 

suppression character. In the NetView program, a 
user-defined character that is coded at the beginning of 
a command list statement or a command to prevent the 
statement or command from appearing on the opera- 
tor's terminal screen or in the network log. 

SVC. (1) Supervisor call. (2) Switched virtual circuit. 

switched virtual circuit (SVC). An X.25 circuit that is 
dynamically established when needed. The X.25 equiv- 
alent of a switched line. 

system management facility (SMF). A standard feature 
of MVS that collects and records a variety of system 
and job-related information. 

system services control point (SSCP). In SNA, a 
central location point within an SNA network for man- 
aging the configuration, coordinating network operator 
and problem determination requests, and providing 
directory support and other session services for end 
users of the network. Multiple SSCPs, cooperating as 
peers, can divide the network into domains of control, 
with each SSCP having a hierarchical control relation- 
ship to the physical units and logical units within its 
domain. 

system services control point (SSCP) domain. The 

system services control point and the physical units 
(PUs), logical units (LUs), links, link stations and all the 
resources that the SSCP has the ability to control by 
means of activation requests and deactivation 
requests. 

Systems Network Architecture (SNA). The description 
of the logical structure, formats, protocols, and opera- 
tional sequences for transmitting information units 



through and controlling the configuration and operation 
of networks. 

System Support Programs (SSP). An IBM licensed 
program, made up of a collection of utilities and small 
programs, that supports the operation of the NCP. 

TAF. Terminal access facility. 

takeover. The process by which the failing active sub- 
system is released from its extended recovery facility 
(XRF) sessions with terminal users and replaced by an 
alternate subsystem. See resource takeover. 

task. A basic unit of work to be accomplished by a 
computer. The task is usually specified to a control 
program in a multiprogramming or multiprocessing 
environment. 

task panel. Online display from which you communi- 
cate with the program in order to accomplish the pro- 
gram's function, either by selecting an option provided 
on the panel or by entering an explicit command. See 
help panel. 

TCAS. Terminal control address space. 

telecommunication line. Any physical medium such as 
a wire or microwave beam, that is used to transmit 
data. Synonymous with transmission line. 

terminal. A device that is capable of sending and 
receiving information over a link; it is usually equipped 
with a keyboard and some kind of display, such as a 
screen or a printer. 

terminal access facility (TAF). In the NetView 
program, a facility that allows a network operator to 
control a number of subsystems. In a full-screen or 
operator control session, operators can control any 
combination of such subsystems simultaneously. 

terminal control address space (TCAS). The part of 
TSO/VTAM that provides logon services for TSO/VTAM 
users. 

TERMINATE. In SNA, a request unit that is sent by a 
logical unit (LU) to its system services control point 
(SSCP) to cause the SSCP to start a procedure to end 
one or more designated LU-LU sessions. 

time-out. (1) (ISO) An event that occurs at the end of 
a predetermined period of time that began at the occur- 
rence of another specified event. (2) A time interval 
allotted for certain operations to occur; for example, 
response to polling or addressing before system opera 
tion is interrupted and must be restarted. 

time sharing option (TSO). An optional configuration of 
the operating system that provides conversational time 
sharing from remote stations. 
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token. A sequence of bits passed from one device to 
another along the token ring. When the token has data 
appended to it, it becomes a frame. 

transmission control (TC) layer. In SNA, the layer 
within a half-session that synchronizes and paces 
session-level data traffic, checks session sequence 
numbers of requests, and enciphers and deciphers 
end-user data. Transmission control has two compo- 
nents: the connection point manager and session 
control. See also half-session. 



transmission line. 

line. 



Synonym for telecommunication 



TSO. Time sharing option. 

type 2.1 node (T2.1 node). A node that can attach to an 
SNA network as a peripheral node using the same pro- 
tocols as type 2.0 nodes. Type 2.1 nodes can be 
directly attached to one another using peer-to-peer pro- 
tocols. See end node, node, and subarea node. See 
also node type. 

type 2.1 node (T2.1 node) control point domain. The 

CP, its logical units (LUs), links, link stations, and all 
resources that it activates and deactivates. 

unformatted, in VTAM, pertaining to commands (such 
as LOGON or LOGOFF) entered by an end user and 
sent by a logical unit in character form. The 
character-coded command must be in the syntax 
defined in the user's unformatted system services defi- 
nition table. Synonymous with character-coded. Con- 
trast with field-formatted. 

uninterpreted name. In SNA, a character string that a 
system services control point (SSCP) is able to convert 
into the network name of a logical unit (LU). Typically, 
an uninterpreted name is used in a logon or Initiate 
request from a secondary logical unit (SLU) to identify 
the primary logical unit (PLU) with which the session is 
requested. 

unsolicited message. A message, from VTAM to a 
program operator, that is unrelated to any command 
entered by the program operator. Contrast with solic- 
ited message. 

upstream. In the direction of data flow from the end 
user to the host. Contrast with downstream. 

user. Anyone who requires the services of a com- 
puting system. 

user-application network. A configuration of data proc- 
essing products, such as processors, controllers, and 
terminals, established and operated by users for the 
purpose of data processing or information exchange, 
which may use services offered by communication 



common carriers or telecommunication Adminis- 
trations. Contrast with public network. 

USERVAR. Contains an application name used to 
route a session-establishment request to the currently 
active application subsystem. 

value. (1) (TC97) A specific occurrence of an attri- 
bute, for example, "blue" for the attribute "color." (2) A 
quantity assigned to a constant, a variable, a param- 
eter, or a symbol. 

variable, in the NetView program, a character string 
beginning with & that is coded in a command list and is 
assigned a value during execution of the command list. 

verb. (1) In SNA, the general name for a transaction 
program's request for communication services. (2) In 
VTAM, a programming language element in the logical 
unit (LU) 6.2 application program interface (API) that 
causes an LU 6.2 function to be performed. 

virtual disk. (1) A logical subdivision (or all) of a phys- 
ical disk pack in the VM operating system that has its 
own virtual device address, consecutive virtual cylin- 
ders, and a volume table of contents (VTOC) or disk 
label identifier. (2) Synonymous with minidisk. 

Virtual Machine (VM). A licensed program whose full 
name is the Virtual Machine/System Product (VM/SP). 
It is a software operating system that manages the 
resources of a real processor to provide virtual 
machines to end users. As a time-sharing system 
control program, it consists of the virtual machine 
control program (CP), the conversational monitor 
system (CMS), the group control system (GCS), and the 
interactive problem control system (IPCS). 

virtual route (VR). In SNA, a logical connection (1) 
between two subarea nodes that is physically realized 
as a particular explicit route, or (2) that is contained 
wholly within a subarea node for intranode sessions. A 
virtual route between distinct subarea nodes imposes a 
transmission priority on the underlying explicit route, 
provides flow control through virtual-route pacing, and 
provides data integrity through sequence numbering of 
path information units (PIUs). See also explicit route 
(ER), path, and route extension. 

virtual route (VR) pacing. In SNA, a flow control tech- 
nique used by the virtual route control component of 
path control at each end of a virtual route to control the 
rate at which path information units (PIUs) flow over the 
virtual route. VR pacing can be adjusted according to 
traffic congestion in any of the nodes along the route. 
See also pacing and session-level pacing. 

virtual route selection exit routine. In VTAM, an 
optional installation exit routine that modifies the list of 
virtual routes associated with a particular class of 
service before a route is selected for a requested 
LU-LU session. 



Glossary 239 



Virtual Storage Extended (VSE). An IBM licensed 
program whose full name is the Virtual Storage 
Extended/Advanced Function. It is a software oper- 
ating system controlling the execution of programs. 

Virtual Telecommunications Access Method (VTAM). 

An IBM licensed program that controls communication 
and the flow of data in an SNA network. It provides 
single-domain, multiple-domain, and interconnected 
network capability. 

VM. Virtual Machine operating system. Its full name is 
Virtual Machine/System Product. Synonymous with 
VM/SP. 

VM/SP. Virtual Machine/System Product operating 
system. Synonym for VM. 



VR. Virtual route. 

VSE. Virtual Storage Extended operating system, 
onymous with VSE/AF. 



Syn- 



VSE/AF. Virtual Storage Extended/Advanced Function 
operating system. Synonym for VSE. 

VTAM. Virtual Telecommunications Access Method 
(IBM licensed program). Its full name is Advanced 
Communications Function for the Virtual Telecommuni- 
cations Access Method. Synonymous with ACF/VTAM. 

VTAM operator command. A command used to 
monitor or control a VTAM domain. See also definition 
statement. 
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Learning About NetView: Operator Training 
(SK2T-0292) is an interactive PC-based operator 
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management concepts to new and inexperienced 
NetView operators. This training package uses 
graphics, animation and interactive NetView product 
simulations in a series of lessons to teach the basics of 
NetView operation. 

NetView Installation and Administration Guide 
(SC31-6018) helps system programmers install and 
prepare the NetView program for operation. It is 
arranged in a simplified, step-by-step style and is 
meant to be used in conjunction with the sample 
network documented in Network Program Products 
Samples. 

NetView Administration Reference (SC31-6014) is for 
system programmers and network operators who need 
a complete understanding of the NetView resource defi- 
nition statements. This book lists each statement in 
alphabetical order giving its purpose and location. 

NetView Tuning Guide (SC31-6079)i describes methods 
for controlling and improving the performance of the 
NetView Release 3 program. It is designed for system 
programmers who need to understand how NetView 
tuning values are determined and optimized. 

NetView Customization Guide (SC31-6016) is designed 
for system programmers and others who want to cus- 
tomize the NetView program to reflect their network's 
needs or operating procedures. This book focuses on 
the different application programming interfaces that 
can be customized and explains how to modify NetView 
help panels and problem determination displays. 

NetView Customization: Using PL/ 1 and C (SC31-6037) 
describes the ways system programmers can tailor the 
NetView program to satisfy unique requirements or 
operating procedures. It discusses the uses and 
advantages of user-written programs (exit routines, 
command processors, and subtasks). It also provides 
instructions in designing, writing, and installing user- 
written programs in PL/I and C. 

NetView Customization: Using Assembler (SC31-6078) 
describes the ways system programmers can tailor the 
NetView program to satisfy unique requirements or 
operating procedures. It discusses the uses and 



advantages of user-written programs (exit routines, 
command processors, and subtasks). It also provides 
instructions in designing, writing, and installing user- 
written programs in Assembler. 

NetView Customization: Writing Command Lists 
(SC31-6015) explains how to simplify network operator 
tasks by using command lists. It provides step-by-step 
instructions for writing simple and advanced command 
lists and for migrating from nccf message automation 
to NetView message automation. 

NetView Operation Primer (SC31-6020) provides a 
basic description of the network management task for 
new network operators. Topics include starting and 
stopping a network, controlling resources, monitoring a 
network, and gathering the necessary data to report a 
problem. 

NetView Operation (SC31-6019) provides system pro- 
grammers and experienced network operators a com- 
prehensive explanation of network management using 
the NetView program. Topics include detailed 
command explanation and panel flows, as well as infor- 
mation on how the various components interact with 
each other. 

NetView Command Summary (SX75-0026) is a refer- 
ence card that provides network operators with the 
format of all the commands and the commonly used 
NetView command lists. The commands are listed in 
alphabetical order by component. 

NetView Problem Determination and Diagnosis 
(LY43-0001) aids system programmers in identifying a 
NetView problem, classifying it, and describing it to an 
ibm Support Center. 

NetView Problem Determination Supplement for Man- 
agement Services Major Vectors 0001 and 0025 
(LD21-0023) describes major vectors 0001 and 0025 for 
system programmers and network operators involved 
in problem determination or diagnosis. The supple- 
ment may be used for the generic alert option and 
other problem determination tasks. 

NetView Resource Alerts Reference (SC31-6024) lists 
the messages sent by NetView-supported hardware 
and software resources. It helps system programmers 
analyze the messages into their component parts: 
action codes, event types, message text, and qualifiers. 
The book is a reference for those who need more infor- 
mation than online help provides. 
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NetView Storage Estimates (SK2T-1988) is an interac- 
tive PC-based tool that helps the user estimate storage 
requirements for NetView. This tool can be used for 
planning, installation, and tuning purposes. It is 
intended for network planners, system programmers, 
and IBM service personnel. 

Console Automation Using NetView: Planning 
(SC31-6058) describes an approach to automate the 
way a system handles messages and responses to 
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beginning such automation, as well as sample plans 
and proposals you might find useful in promoting your 
automation concept. This book includes planning infor- 
mation for MVS, VM, and VSE users of the NetView 
program. 

NetView/PC Publications 

NetView/PC Planning, Installation, and Customization 
(SC31-6002) provides planning, installation, and 
customization information on NetView/PC and explains 
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and downstream to supported devices. Information 
relating to the required pc environment and host pro- 
ducts that support NetView/PC is also provided. It also 
discusses topics that are of general interest when you 
are ordering your equipment. 

NetView/PC Application Program 
Interface/Communications Services Reference 
(SC31-6004) is a reference for os/2 programmers who 
use the api/cs and for system programmers who write 
command processors to run under NetView. The api/cs 
provides a means for vendor and other external appli- 
cations to use the communication services of 
NetView/PC. 

NetView/ PC Operation (SC31-6003) describes how to 
operate the program and diagnose problems in 
NetView/PC. 

NetViewlPC Quick Reference (SX75-0016) describes all 
of the functions of the F-keys throughout the 
NetView/PC program. 



Other Network Program 
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section, see Bibliography and Master Index for 
NetView, NCP, and VTAM. 
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Bibliography and Master Index for NetView, NCP, and 
VTAM (GC31 -6081)2 
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The following list shows the books for vtam V3R2. For 
information about the books for vtam V3R1, V3R1.1, or 
V3R1.2, see any vtam V3R2 book or the Network Program 
Products Bibliography and Master Index. 

VTAM Installation and Resource Definition (SC23-0111) 

VTAM Customization (LY30-5614) 

VTAM Directory of Programming Interfaces for Cus- 
tomers (GC31-6403) 

VTAM Operation (SC23-0113) 

VTAM Messages and Codes (SC23-0114) 

VTAM Programming (SC23-0115) 

VTAM Programming for LU 6.2 (SC30-3400) 

VTAM Diagnosis Guide (LY30-5601) 

VTAM Data Areas for MVS (LY30-5592) 

VTAM Data Areas for VM (LY30-5593) 

VTAM Data Areas for VSE (LY30-5594) 

VTAM Reference Summary (LY30-5600) 

NCP, SSP, and EP Publications 

The following list shows the related books for ncpv4 
and ncp vs. 

NCP, SSP, and EP Generation and Loading Guide 
(SC30-3348) 

NCP, SSP, and Related Products Directory of Program- 
ming Interfaces for Customers (GC31-6202) 

NCP Migration Guide (SC30-3252 for NCP V4 and 
SC30-3440 for NCP V5) 
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NCP, SSP, and EP Resource Definition Guide 
(SC30-3349 for NCP V4 and SC30-3447 for NCP V5) 
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NCP Customization Guide (LY30-5571 for NCP V4 
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SSP Customization (LY43-0021) 
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Planning for a 9370 SNA Distributed Network 
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VM/SP System Product Interpreter User's Guide 
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activating a command list 

See running a command list 
ADDRESS instruction 28 
AFTER command, used to schedule a command 

list 12 
ALLOCATE, NetView command 29 
allocating a data set for NetView 29 
ALL, &CONTROL operand 93 
AND, TRAP operand 35 
APPLID 

NetView command list language control 
variable 82 

REXX function 51 
AREAID 

NetView command list language control 
variable 85 

REXX function 55 
arithmetic operations in assignment statements 91 
Assembler command processors, nesting a REXX 

command list from 29 
ASSIGN command 143 
assignment 

clauses, REXX 23 

statements, NetView command list language 90 
AT command, used to schedule a command list 12 
automation task 18 
automation, message 

See message automation 
AUTOTASK 

command 11 

OST restrictions 18 
AUTOWRAP setting 16 

B 

BEEP, MSGROUTE operand 143 
BEGWRITE control statement 95 
bilingual command list 18 
built-in functions 

NetView command list language 

definition of 99 

in an assignment statement 91 

summary of 178 

&CONCAT 100 

&LENGTH 100 

&NCCFID 101 

&NCCFSTAT 102 

&SUBSTR 103 
REXX 24 



C command processors, nesting a REXX command list 

from 29 
CALL instruction, using 27 
calling another command list 13 
CGLOBAL control statement 126 
clauses, REXX 23 
CLEAR command 93 
CMD 

command 16, 39 
&CONTROL operand 93 
CMDCLASS statement 7 
CM DM DL statement 7 
CNMS8001 EXEC 209 
coding conventions 

bilingual command list 18 
NetView command list language 72 
continuation statements 73 
double-byte character text 74 
suppression character 74 
syntax 72 
REXX 

coding non-REXX commands in a REXX command 

list 24 
record size 24 
suppressing display of a non-REXX 

command 25 
syntax 24 
used in this book xiv 
command list 
activating 

See running a command list 
bilingual 18 
converting NetView command list language to 

REXX 209 
creating 5 

creating a data set for MVS 6 
creating a file for VM 6 
definition of 3 

display, controlling during execution of 20 
dropping from main storage 9 
how a command list can help you 3 
listing a command list in main storage 9 
loading into main storage 7 
message driven 136 
naming 6 
nested 13 
NetView command list language 

See NetView command list language 
network commands, using 14 
Network Control Program, activating 5 
restarting 12 
restrictions 17 
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command list (continued) 
REXX 

See Restructured Extended Executor language 
routing messages from 142 
scope checking 7 
startup, examples 4 
stopping 12 
suspending 12 
system commands, using 14 
updating 5 
uses for 3 
ways to run 

See running a command list 
who can use 7 
command list information 

NetView command list language control 

variables 83 
REXX functions 53 
commands 
AFTER 12 
ALLOCATE 29 
ASSIGN 143 
AT 12 

AUTOMSG 10 
AUTOTASK 11 
BGNSESS 15 
CLEAR 93 
CMD 16, 39 
CMDMDL 7 
DEFAULTS 39 
DELAY 12 
DROPCL 9 
EVERY 12 
EXECIO 28 
FREE 29 
full-screen 16 
GENALERT 11 
GO 12,116 

hardware monitor, using in a command list 14 
LOADCL 8 
long running 

major 15 

minor 15 
MAPCL 9 
message automation 

DOM 141 

WTO 138 

WTOR 140 
MSGROUTE 142 
multi-line messages, used with 

GETMLINE 154 

GETMSIZE 152 

GETMTYPE 153 
NetView, using with REXX WAIT instruction 39 
network 14 
operator 

AFTER 12 

AT 12 

DELAY 12 



commands (continued) 

operator (continued) 
EVERY 12 
running a command list as the result of 12 

OVERRIDE 39 

PARSEL2R 144 

RESET 12,116 

RESTORE TIMER 11 

RETURN 14 

SDOMAIN command 158 

service point command service 
LINKDATA 166 
LINKPD 167 
LINKTEST 166 
RUNCMD 168 

session monitor, using in a command list 14 

STACK 12,116 

status monitor, using in a command list 14 

system 14 

TE 30 

TS 30 

UNIQUE 16 

UNSTACK 12,116 

VIEW 16 

VTAM 14 
comments 

NetView command list language 89 

REXX 23 
common global variables 

NetView command list language 126 

REXX 48 
comparison of NetView command list language to 

REXX 185 
COMPNAME 

NetView command list language control 
variable 83 

REXX function 53 
compression tools, VM REXX, using 27 
CONCAT built-in function 100 
constants, in assignment statements 90 
continuation statements 73 
CONTINUE, &WAIT operand 119 
CONTROL control statement 92 
control statements, NetView command list language 

comparison to REXX instructions 185 

definition of 92 

summary of 179 

&BEGWRITE 95 

&CGLOBAL 126 

&CONTROL 92 

&EXIT 109 

&GOTO 109 

&IF 107 

&PAUSE 97 

&TGLOBAL 124 

&WAIT 111 

&WRITE 94 
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control variables, NetView command list language 

comparison to REXX functions 188 

definition of 81 

summary of 181 

&APPLID 82 

&AREAID 85 

&COMPNAME 83 

&DATE 81 

&DESC 85 

&HCOPY 83 

&HDRMTYPE 86 

&JOBNAME 86 

&JOBNUM 86 

&LINETYPE 86 

&LU 83 

&MCSFLAG 86 

&MSGCNT 84 

&MSGID 84 

&MSGORIGIN 84 

&MSGSTR 85 

&MSGTYP 86 

&NCCFCNT 82 

&OPID 83 

&OPSYSTEM 82 

&PARMCNT 83 

&PARMSTR 83 

&REPLYID 86 

&RETCODE 83 

&ROUTCDE 87 

&SESSID 85 

&SMSGID 87 

&SYSCONID 87 

&SYSID 87 

&TASK 82 

&TIME 81 

&VIEWAID 87 

&VIEWCURCOL 87 

&VIEWCURROW 87 

&VTAM 82 

&WAIT, used with 116 

&WTOREPLY 87 
CONTWAIT, &WAIT operand 119 
converting a NetView command list language command 

list to REXX 209 
creating a command list 5 



DESC (continued) 

REXX function 55 
DISPLAY 

MSGROUTE operand 143 

TRAP operand 35 

&WAIT operand 118 
displaying panels 16 
display, controlling 20 
DOM command 141 
domain information, REXX functions 56 
double-byte character set characters 

coding conventions, NetView command list 
language 74 

continuation characters 74 

in user variables 88 

labels with 75 

PPT, using in a command list running under 17 

&CONCAT, using with 100 

&SUBSTR, using with 104 
DROP instruction 137 
DROPCL command 9 

dropping a command list from main storage 9 
DSICNVRT conversion utility 164 
DSIPUSH macro 15 



editing facilities, for updating a command list 5 
ENDWAIT, &WAIT operand 115, 118 
environment, addressed by REXX, changing 28 
errors, handling 

NetView command list language 115 

REXX 31 
ERROR, &WAIT operand 114 
ERR, &CONTROL operand 93 
EVENT() function, REXX 38 
event, representing as an alert 11 
event=-label pairs, &IF control statement 112 
EVERY command, used to schedule a command 

list 12 
EXECIO command, using in a REXX command list 28 
executing a command list 

See running a command list 
EXIT control statement 109 
expressions 

NetView command list language 90 

REXX 23 



data set, defining for MVS 6 
DATE control variable 81 
DBCS 

See double-byte character set characters 
deallocating a data set from NetView 29 
DEFAULTS command 39 
DELAY command, used to schedule a command 

list 12 
DESC 

NetView command list language control 
variable 85 



file, defining for VM 6 
FLUSHQ instruction 42 
FOR, TRAP operand 37 
FREE, NetView command 29 
full-screen commands, using 16 
function packages, REXX, writing 28 
functions 
built-in 

NetView command list language 



99 
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functions (continued) 
built-in (continued) 

REXX 24 
REXX 

APPLID() 51 

AREAID() 55 

comparison to NetView command list language 
control variables 188 

COMPNAME() 53 

DESC() 55 

EVENT() 38 

HCOPY() 52 

HDRMTYPE() 55 

JOBNAME() 55 

JOBNUM() 55 

LINESIZEO, using 27 

LINETYPE() 55 

LU() 52 

MCSFLAG() 55 

MSGCNT() 53 

MSGID() 53 

MSGORIGNQ 53 

MSGREAD, set by 40 

MSGSTR() 54 

MSGTYP() 56 

MSGVAR() 54 

NVCNT() 56 

NVID() 56 

NVSTAT() 56 

OPID() 52 

OPSYSTEM() 51 

PARMCNT() 53 

REPLYID() 56 

restrictions 27 

ROUTCDEO 56 

SESSID() 54 

SMSGID() 56 

STORAGE(), using 27 

summary of 173 

SYSCONID() 56 

SYSIDO 56 

TASK() 52 

VTAM() 52 

WTOREPLYO 56 



G 



GENALERT command 11 
GETC, GLOBALV operand 49 
GETMLINE command 154 
GETMSIZE command 152 
GETMTYPE command 153 
GETT, GLOBALV operand 46 
global variables 
common 

NetView command list language 126 

REXX 48 
task 

NetView command list language 124 



global variables (continued) 
task (continued) 
REXX 45 
GLOBALV instruction 44 
GO command 12,116 
GOTO control statement 109 

H 

hardware monitor commands, using in a command 

list 14 
HCOPY 

NetView command list language control 

variable 83 
REXX function 52 
HCYLOG, MSGROUTE operand 143 
HDRMTYPE 

NetView command list language control 

variable 86 
REXX function 55 
HOLD, MSGROUTE operand 143 

I 

IC, NCCFIC operand 10 

IF control statement 107 

initialization, running a command list at 10 

instructions, REXX 

ADDRESS 28 

CALL 27 

comparison to NetView command list language 
control statements 185 

definition of 23 

DROP 137 

FLUSHQ 42 

GLOBALV 44 

MSGREAD 40 

PARSE 26 

restrictions 26 

SAY 26 

SIGNAL 31 

summary of 172 

TRACE END 30 

TRACE START 30 

TRAP 34 

WAIT 36 

WAIT CONTINUE 38 

J 

JOBNAME 

NetView command list language control 

variable 86 
REXX function 55 
JOBNUM 

NetView command list language control 

variable 86 
REXX function 55 
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K 

Kanji characters 

See double-byte character set characters 



labels 

NetView command list language 75 

REXX 23 
LENGTH built-in function 100 
LINESIZE function, REXX, using 27 
LINETYPE 

NetView command list language control 
variable 86 

REXX function 55 
LINKDATA command 166 
LINKPD command 167 
LIN KTEST command 166 
listing a command list in storage 9 
LOADCL command 8 
loading a command list into storage 7 
logon, operator, automatically running a command list 

at 11 
long running commands 

major 15 

minor 15 

queuing 16 
LU 

NetView command list language control 
variable 83 

REXX function 52 



M 



major long running commands 15 
MAPCL command 9 
MCSFLAG 

NetView command list language control 

variable 86 
REXX function 55 
message 

automating responses to 135 
continuing to wait for in a command list 
NetView command list language 118 
REXX 38 
multi-line, working with 36, 114, 151 
MVS operator console, sending to 137 
processing information 

NetView command list language control 

variables 84 
REXX functions 53 
queue, flushing 42 
routing from a command list 142 
sending to operators 93 
= -label pairs, coding 115 
message automation 
command lists 
defining 136 



message automation (continued) 
command lists (continued) 

running as the result of 11 
commands 
DOM 141 
GETMLINE 154 
GETMSIZE 152 
GETMTYPE 153 
WTO 138 
WTOR 140 
converting from MVS/OCCF 164 
definition of 135 
implementing 161 
migration 164 
Release 3, how it differs 135 
starting 10 
MESSAGES 

FLUSHQ operand 42 
TRAP operand 35 
WAIT operand 37 
minor long running commands 15 
MINUTES, WAIT operand 37 
MOD, CMDMDL operand 7 
MORE, TRAP operand 35 
MSGCNT 

NetView command list language control 

statement 84,116 
REXX function 40, 53 
MSGID 

NetView command list language control 

statement 84, 116 
REXX function 41,53 
MSGORIGIN, NetView command list language control 

variable 84,116 
MSGORIGN, REXX function 41 , 53 
MSGREAD 

functions set by 40 
REXX instruction 40 
MSGROUTE command 142 
MSGSTR 

NetView command list language control 

statement 85, 117 
REXX function 41,54 
MSGTYP 

NetView command list language control 

statement 86 
REXX function 41,56 
MSGVAR function 41,54 
multi-line messages, working with 36, 114, 151 
MVS 

command 14 

creating a data set for 6 

operator console, sending messages to 137 
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NCCFCNT control variable 82 
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NCCFIC statement 10 
NCCFID 

built-in function 101 
statement 74 
NCCFSTAT built-in function 102 
nested command lists 
definition of 13 
levels of nesting 13 
NetView command list language, using &WAIT 

in 118 
REXX 

from Assembler, C, or PL/I command 

processors 29 
using TRAP in 36 
using WAIT in 40 
testing 13 
NETLOG, MSGROUTE operand 143 
NetView command list language 
coding conventions 72 
comments 89 
comparison to REXX 185 
control statements 

See control statements, NetView command list 
language 
control variables 

See control variables, NetView command list lan- 
guage 
converting to REXX 209 
features of 71 
functions, built-in 91 
labels 75 
null statements 89 
variables 76 
NetView commands 
using with WAIT 39 
using with &PAUSE 98 
using with &WAIT 116 
network commands, using 14 
Network Control Program, activating by command 

list 5 
NOINPUT, &PAUSE operand 97 
NOSUB, &BEGWRITE operand 95 
NO, TRAP operand 36 
null statements 89 
NVCNT function 56 
NVID function 56 
NVSTAT function 56 

o 

ONLY, TRAP operand 35 

operands 

ALL, &CONTROL control statement 93 
AND, TRAP instruction 35 
BEEP, MSGROUTE command 143 
CMD, &CONTROL control statement 93 
CONTINUE, &WAIT control statement 119 
CONTWAIT, &WAIT control statement 119 



operands (continued) 
DISPLAY 

MSGROUTE command 143 

TRAP instruction 35 

&WAIT control statement 118 
ENDWAIT, &WAIT control statement 115,118 
ERROR, &WAIT control statement 1 14 
ERR, &CONTROL control statement 93 
FOR, WAIT instruction 37 
GETC, GLOBALV instruction 49 
GETT, GLOBALV instruction 46 
HCYLOG, MSGROUTE command 143 
HOLD, MSGROUTE command 143 
IC, NCCFIC command 10 
MESSAGES 

FLUSHQ instruction 42 

TRAP instruction 35 

WAIT instruction 37 
MINUTES, WAIT instruction 37 
MOD, CMDMDL statement 7 
MORE, TRAP instruction 35 
NETLOG, MSGROUTE command 143 
NOINPUT, &PAUSE control statement 97 
NOSUB, &BEGWRITE control statement 95 
NO, TRAP instruction 36 
ONLY, TRAP instruction 35 
PUTC, GLOBALV instruction 48 
PUTT, GLOBALV instruction 45 
REPLACE, LOADCL command 8 
SECONDS, WAIT instruction 37 
STRING, &PAUSE control statement 98 
SUB, &BEGWRITE control statement 95 
SUPPCHAR, NCCFID statement 74 
SUPPRESS 

TRAP instruction 35 

&WAIT control statement 118 
SUPP, CNMS8001 EXEC oeprand 210, 21 1 
SYSLOG, MSGROUTE command 144 
VARS, &PAUSE control statement 97 
operator 

command, running a command list as the result 

of 12 
information 

NetView command list language control 
variables 83 

REXX functions 52 
input, pausing for in a REXX command list 26 
logon, running a command list automatically at 11 
sending messages to 93 
task, starting 1 1 
OPID 

NetView command list language control 

variable 83 
REXX function 52 
OPSYSTEM 

NetView command list language control 

variable 82 
REXX function 51 
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OST, AUTOTASK, restrictions 
OVERRIDE command 39 



18 



panel information, NetView command list language 

control variables 87 
panels, displaying 16 
parameter variables, NetView command list 
language 77 
nested command lists, using in 79 
null 81 

passing to a command list 78 
special characters, using in 80 
text strings, using in 80 
&WAIT, using with 116 
PARMCNT 

NetView command list language control 

variable 83 
REXX function 53 
PARMSTR control variable 83 
PARSE instruction 26 
PARSEL2R command 144 
parsing 
template 

using character selectors in 150 
using patterns in 147 
using symbols in 146 
variables 144 
PAUSE control statement 97 

using NetView commands with 98 
pausing for operator input in a REXX command list 26 
performance 

converted command list, improving 214 
using double suppression character 
NetView command list language 74 
REXX 25 
PL/I command processors, nesting a REXX command 

list from 29 
PPT restrictions 17 
PROFILE statement 1 1 
PUTC, GLOBALV operand 48 
PUTT, GLOBALV operand 45 



queue, message, flushing 42 
queuing a long running command 16 
quotes, using in REXX command lists 
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record size 

NetView command list language 72 

REXX 24 
removing a command list from main storage 
REPLACE, LOADCL operand 8 



REPLYID 

NetView command list language control 

variable 86 
REXX function 56 
RESET command 12,116 
RESTORE TIMER command 11 
Restructured Extended Executor language 
command lists 

CALL instruction, using 27 

coding conventions 24 

coding non-REXX commands in 24 

environment addressed by, changing 28 

errors, recovering from 31 

examples 57 

EXECIO command, using in 28 

LINESIZE function, using 27 

nesting from an Assembler, C, or PL/I command 

processor 29 
operator input, pausing for 26 
record size 24 
restrictions 27 
SAY instruction, using 26 
STORAGE function, using 27 
suppressing display of a non-REXX 

command 25 
tracing 30 
comparison to NetView command list language 185 
function packages, writing 28 
functions 

See functions 
instructions 

See instructions, REXX 
introduction to 23 
VM compression tools, using 27 
RETCODE control variable 83 
return codes 

NetView command list language 83 
REXX 31 
RETURN command, restriction on use of 14 
REXX 

See Restructured Extended Executor language 
ROUTCDE 

NetView command list language control 

variable 87 
REXX function 56 
RUNCMD command 168 
running a command list 
after a time interval 12 
after the operator logs on 11 
at a specified time 12 
by an operator command 12 
from a user-written command processor 14 
from another command list 13 
when NetView is started 10 
when NetView receives a message 11 
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SAY instruction, using 26 
scope checking 

command lists 7 

variables, NetView command list language 127 
SDOMAIN command 158 
SECONDS, WAIT operand 37 
service point command service commands 165 
SESSID 

NetView command list language control 
variable 85 

REXX function 54 
session 

information 

NetView command list language control 

variables 82 
REXX functions 51 

monitor commands, using in a command list 14 

TAF 4 
SIGNAL instruction 31 
SMSGID 

NetView command list language control 
variable 87 

REXX function 56 
STACK command 12,116 

status monitor commands, using in a command list 14 
storage 

loading command lists into 8 

removing command lists from 9 
STORAGE() function, using 27 
STRING, &PAUSE operand 98 
SUBSTR built-in function 103 

using with DBCS characters 104 
SUB, &BEGWRITE operand 95 
SUPPCHAR, NCCFID operand 74 
SUPPRESS 

TRAP operand 35 

&WAIT operand 118 
suppressing 

display of non-REXX commands in a REXX command 
list 25 

messages 161 
suppression characters 74 
SUPP, CNMS8001 operand 210 
SYSCONID 

NetView command list language control 
variable 87 

REXX function 56 
SYSID 

NetView command list language control 
variable 87 

REXX function 56 
SYSLOG, MSGROUTE operand 144 
system commands, using 14 
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TAF 

command output 16 

sessions 4 
TASK 

NetView command list language control 
variable 82 

REXX function 52 
task global variables 

NetView command list language 124 

REXX 45 
TE command 30 
terminal information 

NetView command list language control 
variables 83 

REXX functions 52 
TGLOBAL control statement 124 
THEN clause, &IF control statement 108 
TIME control variable 81 
time intervals, running a command list at 12 
tokens, message 

NetView command list language 113 

REXX 35 
Trace End command 30 
Trace Start command 30 
tracing, REXX command lists 30 
TRAP 

REXX instruction 34 

using in a nested REXX command list 36 
TS command 30 
TSO/E EXECIO command 28 
TSO, executing CNMS8001 on 210 

u 

UNIQUE command 16 
UNSTACK command 12,116 
user variables 87 

user-written command processor, activating a 
command list 14 

v 

variables 

command list information 

NetView command list language 83 

REXX 53 
control 

See control variables, NetView command list lan- 
guage 
global 

See global variables 
operator information 

NetView command list language 83 

REXX 52 
panel information, NetView command list 

language 87 
parameter 
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variables (continued) 
parameter (continued) 

See parameter variables, NetView command list 
language 
parsing 144 
session information 

NetView command list language 82 
REXX 51 
substitution order 76 
terminal information 

NetView command list language 83 
REXX 52 
user 87 
VARS, &PAUSE operand 97 
VIEW command 16 
VIEWAID control variable 87 
VIEWCURCOL control variable 87 
VIEWCURROW control variable 87 
VM 

defining file for 6 
executing CNMS8001 on 212 
REXX compression tools, using 27 
VTAM 

NetView command list language control 

variable 82 
REXX function 52 

w 

WAIT 

NetView command list language control 
statement 111 
control and parameter variables used with 116 
ending 115,119 

nested command lists, using in 118 
NetView commands, using with 116 
REXX instruction 36 

nested REXX command lists, using in 40 
NetView commands, using with 39 
WAIT CONTINUE instruction 38 
WRITE control statement 94 
WTO command 138 
WTOR command 140 
WTOREPLY 

NetView command list language control 

variable 87 
REXX function 56 
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&EXIT control statement 109 
&GOTO control statement 109 
&HCOPY control variable 83 
&HDRMTYPE control variable 86 
&IF control statement 107 
&JOBNAME control variable 86 
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&MCSFLAG control variable 86 
&MSGCNT control variable 84 
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&MSGORIGIN control variable 84 
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&OPSYSTEM control variable 82 
&PARMCNT control variable 83 
&PARMSTR control variable 83 
&PAUSE control statement 97 
&REPLYID control variable 86 
&RETCODE control variable 83 
&ROUTCDE control variable 87 
&SESSID control variable 85 
&SMSGID control variable 87 
&SUBSTR built-in function 103 
&SYSCONID control variable 87 
&SYSID control variable 87 
&TASK control variable 82 
&TGLOBAL control statement 124 
&THEN clause, &IF control statement 
&TIME control variable 81 
&VIEWAID control variable 87 
&VIEWCURCOL control variable 87 
&VIEWCURROW control variable 87 
&VTAM control variable 82 
&WAIT control statement 1 1 1 
&WRITE control statement 94 
&WTOREPLY control variable 87 
&1 - &31 parameter variables 117 



108 



Special Characters 

(SUPP, CNMS8001 operand 211 
&APPLID control variable 82 
&AREAID control variable 85 
&BEGWRITE control statement 95 
&CGLOBAL control statement 126 
&COMPNAME control variable 83 
&CONCAT built-in function 100 



Index 253 



Readers Comment Form 



NetView™ 

Customization: Writing Command Lists 

Release 3 

Publication No. SC31-6015-0 

This manual is part of a library that serves as a reference source for systems 
analysts, programmers, and operators of IBM systems. You may use this form to 
communicate your comments about this publication, its organization, or subject 
matter, with the understanding that IBM may use or distribute whatever information 
you supply in any way it believes appropriate without incurring any obligation to 
you. 

Note: Copies of IBM Publications are not stocked at the location to which this form 
is addressed. Please direct any requests for copies of publications, or for 
assistance in using your IBM system, to your IBM representative or to the IBM 
branch office serving your locality. 

Possible topics for comment are: clarity, accuracy, completeness, organization, 
coding, retrieval, and legibility. 

Comments: 



What is your occupation? 



If you wish a reply, give your name, company, mailing address, and date: 



Thank you for your cooperation. No postage stamp necessary if mailed in the 
U.S.A. (Elsewhere, an IBM office representative will be happy to forward your 
comments or you may mail directly to the address in the Edition Notice on the back 
of the title page.) 



SC31-6015-0 



Reader's Comment Form 



Fold and tape 



Please Do Not Staple 



Fold and tape 



BUSINESS REPLY MAIL 

FIRST CLASS PERMIT NO. 40 ARMONK, N.Y. 



POSTAGE WILL BE PAID BY ADDRESSEE 

International Business Machines Corporation 

Dept. E15 

P.O. Box 12195 

Research Triangle Park, N.C. 27709-9990 



NO POSTAGE 

NECESSARY 

IF MAILED 

IN THE 

UNITED STATES 



Fold and taps 



Please Do Not Staple 



Fold and tap* 



